GuidesAPI ReferenceDiscussions

Astropay Voucher Redirect Deposit

Suggest Edits

Astropay VoucherRedirectDeposit is a payment method to offer Deposit through Astropay with redirect voucher options from Mexico and Columbia.

It supports the following options:

  • from OXXO, ToditoCash and Paynet from Mexico.
  • some others from Columbia.

The following method IDs are covered in this section:

IDNameCredit/Debit State
299VoucherRedirectDepositDepositedByProvider

Payment method interaction type: Redirection to External Payment Provider (see Interaction Types).

Product description - OXXO

Please find below some details about the product voucher OXXO.

QuestionAnswer
Supported currencies MXN and USD
Min and Max per transaction limit Min 2 USD, Max 10000 MXN

There are specific daily, weekly and monthly limits. Daily, weekly, monthly and transaction limits vary by merchant.

There is a limit of 10.000 MXN per OXXO voucher. The user may issue several OXXO vouchers till the daily limit is met.
Default validity period of the voucher 3 days
validity period cannot be extended
expired voucher A user cannot pay with an expired voucher

When a voucher is expired, Astropay sends a notification to PXP Financial. The payment is put into RefusedByProvider state.
re-use of voucher A voucher cannot be re-used
different amount A user may not pay a different amount. For a voucher generated for MXN 100, the user may not pay MXN 50 or MXN 150 instead.
Notification time The turnaround time for voucher payment notifications is less than 24 hours (after a voucher is paid at an OXXO store). Voucher payments are not notified on Sundays and Bank holidays.

Hence, if a voucher is paid on Saturday 19:00, is it notified on Monday.
ChargebacksNot possible
Identification numberThe identification number (CURP/RFC/IFE) is only validated by length (alphanumeric 10-18 lenght). If not valid, then error Invalid CPF is returned.
Reference numberThe reference number (referencia) is saved by PXP Financial in the field ProviderTransactionID and this field is included in the initiatePaymentResponse. (Astropay sends the reference number in the field x_document in the IPN message)
Additional servicesAstropay can send the voucher details to the user´s eMail. Astropay can also send a reminder email one day before the voucher is due to expiry. Both functions can be configured at Astropay.

The user flow is:

  • the user selects the payment method
  • user is redirected to Astropay page
  • voucher with a barcode and number is generated on provider page
  • user can either print the voucher or copy the barcode number or scan it with their phone
  • provider notifies the payment status

Product description - Paynet

Please find below some details about the product voucher Paynet.

QuestionAnswer
Supported currencies USD and MXN
.. but the payment has to be made in MXN
Min and Max per transaction limit Min 2 USD, Max 30.000 MXN per voucher

There are specific daily, weekly and monthly limits. Daily, weekly, monthly and transaction limits vary by merchant.

There is a limit of 30.000 MXN per Paynet voucher. The user may issue several Paynet vouchers till the daily limit is met.
Default validity period of the voucher 5 days
validity period can be extended
expired voucher A user cannot pay with an expired voucher

When a voucher is expired, Astropay sends a notification to PXP Financial and PXP Financial puts the payment to RefusedByProvider state.

If a payment is done with an expired voucher, the payment has to be released by Astropay manually and only if the user provides the payment proof.
re-use of voucher A voucher cannot be re-used
different amount A user may not pay a different amount. For a voucher generated for MXN 100, the user may not pay MXN 50 or MXN 150 instead.
Notification time Notification takes place immediately after the user pays.
ChargebacksNot possible
Identification numberThe identification number (CURP/RFC/IFE) is only validated by length (alphanumeric 10-18 lenght). If not valid, then error Invalid CPF is returned.
Additional servicesAstropay can send the voucher details to the user´s eMail. Astropay can also send a reminder email one day before the voucher is due to expiry. Both functions can be configured at Astropay.
Popularity of Paynet storesPlease find the Paynet stores listed by popularity:

Walmart
7 eleven
Farmacias del ahorro
Sams Club
Bodega Aurrera
Suprema
Cirulo K
Farmacia Benavides
Store locatorStore locator for Paynet.

Product Description - ToditoCash

ToditoCash is a Prepaid Voucher.
The customer goes to a store that accepts Todito Cash payments and deposits any given amount. Then that amount will be associated to a number the user can use to pay as if it were a card.

The user will input a “card number” once redirected.

The user will buy any amount he wants at a store offering Todito Cash vouchers. He will be able to use it to pay different services multiple times (with a number like a debit card). So, for example he can pay a voucher of 100 MXN but then use it on a 50 MXN payment. He will have the rest for future usage.

Sample pages

The text on the top of the voucher is:

Imprime y presenta este comprobante en cualquier tienda Oxxo del país para realizar el pago por tu compra. Indica al cajero de la tienda el valor exacto que figura en el presente comprobante. De lo contrario es probable que no podamos validar correctamente la compra.

Translated:

Print and present this voucher at any Oxxo store in the country to make the payment for your purchase. Tell the cashier of the store the exact value shown in this voucher. Otherwise it is likely that we can not validate the purchase correctly.

The text at the bottom of the OXXO voucher is:

• El presente comprobante solo es válido para el pago que estás efectuando y se verá reflejado en la cuenta del comercio 24 horas después de haberse realizado.
• Si tienes dudas adicionales acerca del pago, envía un correo a [email protected]
• Una vez recibido tu pago en Oxxo, AstroPay informará al comercio, el cual procederá a hacer entrega del producto/servicio que estás adquiriendo.

Translated:

• This voucher is only valid for the payment you are making and it will be reflected in the account of the trade 24 hours after it has been made.
• If you have additional questions about the payment, send an email to [email protected]
• Once your payment is received at Oxxo, AstroPay will inform the merchant, which will proceed to deliver the product / service you are acquiring.

In the middle section of the voucher the following items are shown:

  • merchant
  • reference (referencia)
  • expiry date (fecha expiración)
  • value (valor)

At the bottom there´s a button to print and a button to go back.

The voucher for Bodega Aurrera (BW; above) is the same as the voucher for Circulo K (CU; below), as all payment vouchers look the same. The different codes are just to offer a list of available payment methods to the end customer.

Please find below a translated text as a image:

Redirect Integration

Currently not supported.

Backend2BackendIntegration

The following parameters are expected in initiatePaymentRequest.specificPaymentData:

key (value type, account type, required)value
SuccessPageUrl
(string, required)		URL for redirecting the customer after the payment. Redirection to the URL does not imply a successful payment.
PaymentDescription (string)Description text, maximum 200 characters.
ProductCode (string, required)Code of the Voucher type that is used to make the payment. Format is 2 chars abbreviation, refer to the table below.

📘

Supported vouchers for Mexico

OX - OXXO

BW - Bodega Aurrera

CU - Circulo K

EN - 7 Eleven

FA - Farmacias del ahorro

FB - Farmacia Benavides

SS - Sams Club

SU - Superama

WA - Walmart

TC - ToditoCash

PN - PayNet

Note: These vouchers (except OXXO) are a group of stores also knows as Paynet.

📘

Supported vouchers for Columbia:

BU - Baloto (no longer supported by D24)
EY - efectly
RV - Red Servi
EX - exito
CR - Carulla
SX - Surtimax

The following parameters are expected in initiatePaymentRequest.userData:

key (value type, account type, required)value
address.countryCode2 (string, required)Upper case two-letter country code (ISO 3166).
identificationNumber (string, required)Identification Number is one of the following: CURP/RFC/IFE. CC for Columbia.

Astropay validates the number length.
telephoneNumber (string, optional)For Columbia, the mobile phone number needs to be provided here. Optional for all other countries and can thus be omitted.

❗️

Identification Number

For Mexico, the field IdentificationNumber should be the CURP or RFC or IFE number.
For Columbia it should be CC.

Example initiatePaymentRequest:

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<merchantID>MyMerchant</merchantID>
	<shopID>MyShop</shopID>
	<merchantTransactionID>d359e871-05d0-4500-8ff1-8151d3a33b94</merchantTransactionID>
	<paymentMethodID>299</paymentMethodID>
	<amount currencyCode="MXN">99.99</amount>
	<userID>7a1e49d6-f937-4627-ae14-0e3412</userID>
	<userData>
		<username>7a1e49d6-f937-4627-ae14-0e3412</username>
		<firstname>José</firstname>
		<lastname>Luis</lastname>
		<currencyCode xsi:nil="true" />
		<languageCode xsi:nil="true" />
		<email>[email protected]</email>
		<address>
			<street>PROVIDENCIA 726 NO. S/N, DEL VALLE CENTRO, 03100</street>
			<houseName xsi:nil="true" />
			<houseNumber xsi:nil="true" />
			<houseNumberExtension xsi:nil="true" />
			<postalCode>03100</postalCode>
			<city>DISTRITO FEDERAL</city>
			<state>Benito Juá</state>
			<countryCode2>MX</countryCode2>
			<telephoneNumber xsi:nil="true" />
		</address>
		<dateOfBirth>yyyy-mm-ddThh:mm:ss</dateOfBirth>
		<identificationNumber>POGT921111HCHRSS00</identificationNumber>
		<identificationNumberType xsi:nil="true" />
		<drivingLicenseNumber xsi:nil="true" />
		<drivingLicenseIssuingState xsi:nil="true" />
	</userData>
	<userIP>127.0.0.1</userIP>
	<userSessionID>59adab5e-f7c2-44c9-bd4d-39d1272ffd02</userSessionID>
	<creationTypeID>1</creationTypeID>
	<specificPaymentData>
		<data xsi:type="keyStringValuePair">
			<key>SuccessPageUrl</key>
			<value>http://success/?a=b&amp;c=d</value>
		</data>
		<data xsi:type="keyStringValuePair">
			<key>PaymentDescription</key>
			<value>Description text, maximum 200 characters.</value>
		</data>
		<data xsi:type="keyStringValuePair">
			<key>ProductCode</key>
			<value>OX</value>
		</data>
	</specificPaymentData>
</initiatePaymentRequest>

Example initiatePaymentResponse:

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.cqrpayments.com/PaymentProcessing">
	<payment xsi:type="paymentWithPaymentAccount">
		<merchantID>MyMerchant</merchantID>
		<shopID>MyShop</shopID>
		<paymentMethod>
			<key>299</key>
			<value>VoucherRedirectDeposit</value>
		</paymentMethod>
		<merchantTransactionID>d359e871-05d0-4500-8ff1-8151d3a33b94</merchantTransactionID>
		<paymentID>04a0322d-bed4-4ed3-b155-f85ea2109be2</paymentID>
		<userID>7a1e49d6-f937-4627-ae14-0e3412</userID>
		<paymentProvider>
			<key>152</key>
			<value>Astropay</value>
		</paymentProvider>
		<amount currencyCode="MXN">99.99</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>127.0.0.1</userIP>
		<state>
			<id>219020a2-8b19-4608-a2e9-44b3d326b139</id>
			<definition>
				<key>30</key>
				<value>RedirectURLCreated</value>
			</definition>
			<createdOn>2018-02-06T10:22:01.6925872Z</createdOn>			
      <description>[[URL to redirect the user to]]</description>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>RedirectionUrl</key>				    	
          <value>[[URL to redirect the user to]]</value>
				</detail>
				<detail xsi:type="keyStringValuePair">
					<key>PaymentStateReasonID</key>
					<value>1</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>false</isExecuted>
		<baseAmount currencyCode="EUR">4.32</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>LocalAmount</key>
				<value>99.99</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>LocalCurrency</key>
				<value>MXN</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>UsdAmount</key>
				<value>5.32</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>AmountToDeposit</key>
				<value>99.99</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>04a0322d-bed4-4ed3-b155-f85ea2109be2</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>68150165</value>
			</detail>
		</paymentDetails>
		<paymentAccount>
			<paymentAccountID>0</paymentAccountID>
		</paymentAccount>
	</payment>
</initiatePaymentResponse>

Notifications

The standard notification mechanism is used for notifying the merchant in the background (asynchronously) about payment state changes. For more information see PaymentStateChangedNotification.

Example handlePaymentStateChangedNotificationRequest for a successful payment:

<?xml version="1.0" encoding="utf-16"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<payment xmlns:q1="http://www.cqrpayments.com/PaymentProcessing" xsi:type="paymentWithPaymentAccount">
		<merchantID>MyMerchant</merchantID>
		<shopID>MyShop</shopID>
		<paymentMethod>
			<key>299</key>
			<value>VoucherRedirectDeposit</value>
		</paymentMethod>
		<merchantTransactionID>da8ac4f5-7520-4c22-bb37-8f658888f627</merchantTransactionID>
		<paymentID>580b7e51-7ca2-400b-a35e-6e0a2ac7bd04</paymentID>
		<userID>1707ad80-1035-4778-9b20-f7fac5</userID>
		<paymentProvider>
			<key>152</key>
			<value>Astropay</value>
		</paymentProvider>
		<amount currencyCode="MXN">99.9900</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>127.0.0.1</userIP>
		<state>
			<id>568909b7-8f1e-4e12-9a0b-66e27d75d983</id>
			<definition>
				<key>29</key>
				<value>DepositedByProvider</value>
			</definition>
			<createdOn>2018-02-06T14:02:35.353</createdOn>
			<description>[[Status description message]]</description>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderErrorMessage</key>
					<value>[[Provider error message]]</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>true</isExecuted>
		<baseAmount currencyCode="EUR">4.3200</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>580b7e51-7ca2-400b-a35e-6e0a2ac7bd04</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>LocalAmount</key>
				<value>99.99</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>LocalCurrency</key>
				<value>MXN</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>UsdAmount</key>
				<value>5.32</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>AmountToDeposit</key>
				<value>99.99</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>68150165</value>
			</detail>
		</paymentDetails>
		<paymentAccount>
			<paymentAccountID>0</paymentAccountID>
		</paymentAccount>
	</payment>
</handlePaymentStateChangedNotificationRequest>

Example handlePaymentStateChangedNotificationRequest for a failed payment:

<?xml version="1.0" encoding="utf-16"?>
<handlePaymentStateChangedNotificationRequest xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
	<payment xmlns:q1="http://www.cqrpayments.com/PaymentProcessing" xsi:type="paymentWithPaymentAccount">
		<merchantID>MyMerchant</merchantID>
		<shopID>MyShop</shopID>
		<paymentMethod>
			<key>299</key>
			<value>VoucherRedirectDeposit</value>
		</paymentMethod>
		<merchantTransactionID>ed3369e6-3f52-434b-b2d3-b59284b0a6a4</merchantTransactionID>
		<paymentID>89a774f0-6393-4dae-add7-0d154eb55ae8</paymentID>
		<userID>1707ad80-1035-4778-9b20-f7fac5</userID>
		<paymentProvider>
			<key>152</key>
			<value>Astropay</value>
		</paymentProvider>
		<amount currencyCode="MXN">99.9900</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>127.0.0.1</userIP>
		<state>
			<id>c3a70510-9983-4b27-8886-8df12f2b42e2</id>
			<definition>
				<key>100</key>
				<value>RefusedByProvider</value>
			</definition>
			<createdOn>2018-02-06T15:49:46.9</createdOn>
			<description>[[Status description message]]</description>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderErrorMessage</key>
					<value>[[Provider error message]]</value>
				</detail>
				<detail xsi:type="keyIntValuePair">
					<key>PaymentStateReasonID</key>
					<value>1</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>false</isExecuted>
		<baseAmount currencyCode="EUR">4.3200</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>89a774f0-6393-4dae-add7-0d154eb55ae8</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>LocalAmount</key>
				<value>99.99</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>LocalCurrency</key>
				<value>MXN</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>UsdAmount</key>
				<value>5.32</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>AmountToDeposit</key>
				<value>99.99</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderTransactionID</key>
				<value>68150165</value>
			</detail>
		</paymentDetails>
		<paymentAccount>
			<paymentAccountID>0</paymentAccountID>
		</paymentAccount>
	</payment>
</handlePaymentStateChangedNotificationRequest>l

Testing instruction (Mock)

📘

Mock Testing

The following section describes mock testing. Provider testing requires special configuration at provider. See further below on provider testing.

The link to access the Mock is in the initiatePaymentResponse:

https://test2.backend.cqrpayments.com/WebMockProviders/AstropayFrontend/Index?x_invoice=ad5a8bfc-4e2c-44a4-9b72-2bb878a90c86

To send a payment to the "DepositedByProvider" state:

leave the password field as it is
set the Result dropdown to "Success"
Click the "Submit Confirmation" button
Expected result:

redirected to the success page url provided in the initiatePaymentRequest:
SuccessPageUrl
http://success/?a=b&c=d
shop notification received
To send a payment to the "RefusedByProvider" state

leave the password field as it is
set the Result dropdown to "Refused"
Click the "Submit Confirmation" button
Expected result:

redirected to the success page url provided in the initiatePaymentRequest:
SuccessPageUrl
http://success/?a=b&c=d
shop notification received
TABLE OF CONTENTS
Redirect Integration
Backend2BackendIntegration
Notifications
Testing instructions

Testing instruction (Provider)

In order to set a transaction to COMPLETED, it needs to be in PENDING status before. And to set a transaction as PENDING, the merchant tester will need to navigate to the payment link.

In order to check the transaction status at the provider, please login here

Updated 7 months ago