GuidesAPI ReferenceDiscussions
Guides

Aircash Abon Direct Voucher Deposit

Suggest Edits

📘

Abon flows

PXP supports 2 different Abon flow:

  • Abon flow with a redirect - see here
    User is being redirected to the Aircash frame to enter the 16 digit voucher code. In some countries the user will also be asked to enter his mobile phone number to authenticate the payment in the Aircash app.
  • Abon flow without a redirect - THIS PAGE!
    User is not being redirected, rather user stays on the merchant´s cashier site to enter voucher code and mobile phone number.
    Lower risk of abandoment by the customer, but merchant needs to inform the customer if the authentication via the Aircash app is required.

Aircash Abon Voucher enables users to make payments to their accounts via paper vouchers that can be bought at cash registers, ie. points of sales of Aircash Sales partners (kiosks, gas stations, etc.)

The user logs into a merchants website and chooses to deposit money via an Aircash Abon voucher. He then enters the 16-digit code from the coupon he bought, and optionally confirms the transaction of funds to the merchant account via the Aircash app.

Confirmation is mandatory for certain markets such as Germany.

The funds then are credited to the user´s online account and the coupon can no longer be used (no partial redemption).

The following method IDs are covered in this section:

IDNameCredit/Debit State
443Aircash Voucher DepositDepositedByProvider (29)

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

Flow

Redirect Integration

Currently not supported.

Backend2BackendIntegration

The following parameters can be provided in initiatePaymentRequest.specificPaymentData:

key (value type, account type, required)value
SerialNumber (string, required)16-digit voucher code - only the presence of the parameter is validated, but not it´s format
PhoneNumber (string, optional)Phone number must be in MSISDN format, e.g. 385981234567, 385 being the country code, 98 the operator code and 1234567 the user number.

📘

Amount

An Abon voucher payment is initiated without an amount, but with the currency!

The following parameters can / should be provided in InitiatePaymentRequest.UserData:

key (value type, account type, required)value
FirstNameuser´s first name
Lastnameuser´s last name
DateOfBirthuser´s date of birth
identificationNumberuser´s identification number (e.g. Codice Fiscale in Italy)

Parameters FirstName, LastName and DateOfBirth are only sent to provider Aircash if all of them can be populated from the user details; otherwise parameters are not sent. Additionally identificationNumber is sent only if also FirstName, LastName and DateOfBirth are present on the user.

After the request has been sent to provider Aircash, then payment may go to one of the following states and they will be returned in initiatePaymentResponse:

StateDescription
InitiateRequestProviderCommunicationErrorOccurredNo response was received from provider Aircash

Note: Payments could be moved from this state to InitiatedByProvider, AuthorizedByProvider, InitiateErrorReportedByProvider or InitiateRefusedByProvider.

This transition could be removed / deactivated on the merchant´s request.

If a payment will stay in that state, it could be already authorised by the user (or does not need authorisation). Still the payment will not be executed as sending an executePaymentAction is not allowed in that state.
InitiateRefusedByProviderThe request was refused by provider Aircash, a ProviderResponseCode and ProviderResponseMessage was sent and will be returned in the initiatePaymentResponse.
InitiateErrorReportedByProviderAn error response was returned by provider. An error message has been saved in ProviderErrorResponseMessage and will be returned in the initiatePaymentResponse.
AuthorisedByProviderThe payment is authorized - if necessary - and ready to be confirmed by the merchant.
The initiatePaymentResponse will also include the details OriginalVoucherISOCurrency, OriginalVoucherValue CurrentVoucherValue, and ProviderUserID , if present.
InitiatedByProviderThe payment is initiated, but has to be approved by the end-user by entering his phone number.
The initiatePaymentResponse will also include the details OriginalVoucherISOCurrency, OriginalVoucherValue CurrentVoucherValue and ProviderUserID , if present.

After the payment has been approved by the end-user, PXP will be notified. PXP will query the payment state with provider and move it to AuthorisedByProvider. The merchant will receive a notification and then may confirm the payment.

PXP will query payments sitting in InitiatedByProvider and update their status if needed; alternatively payments may be moved to Expired if not further action has taken place.

The payment amount will also be updated and returned in the initiatePaymentResponse.

The following details will be returned in initiatePaymentResponse when the payment state is either AuthorisedByProvider or InitiatedByProvider:

ValueSource ValueDescription
OriginalVoucherISOCurrencyOriginalISOCurrencyISO 4217 code of the currency that the coupon was originally bought in
OriginalVoucherValueOriginalCouponValueCoupon value in the currency that the coupon was originally bought in
CurrentVoucherValueCurrentCouponValueCurrent coupon value in the currency that the coupon was originally bought in
ProviderUserIDAircashUserIDAircash user identifier (null if authorization was not used)

Example initiatePaymentRequest:

<initiatePaymentRequest xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <merchantID>{{merchant}}</merchantID>
    <shopID>{{shop}}</shopID>
    <merchantTransactionID>{{merchantTransactionID}}</merchantTransactionID>
    <paymentMethodID>443</paymentMethodID>
    <amount currencyCode="EUR">0.00</amount>
    <userID>{{newUserID}}</userID>
    <userData>
        <username>{{newUserName}}</username>
       <firstname>Chloe</firstname>
        <lastname>Ko</lastname>
        <currencyCode>EUR</currencyCode>
        <languageCode>EN</languageCode>
        <email>{{newUserEmail}}</email>
        <address>
            <street>Test street</street>
            <houseNumber>1b</houseNumber>
            <postalCode>1030</postalCode>
            <city>Vienna</city>
            <state>Vienna</state>
            <countryCode2>AT</countryCode2>
            <telephoneNumber>4311141759235</telephoneNumber>
        </address>
        <dateOfBirth>1980-01-01T00:00:00</dateOfBirth>
        <gender>Female</gender>
    </userData>
    <userIP>80.121.151.158</userIP>
    <userSessionID>t02d03hwaxkrl5gmabcypwmm</userSessionID>
    <creationTypeID>1</creationTypeID>
    <specificPaymentData>
        <data xsi:type="keyStringValuePair">
            <key>PaymentDescription</key>
            <value>test</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>SerialNumber</key>
            <value>3639795410216989</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>TelephoneNumber</key>
            <value>4367761759235111</value>
        </data>
    </specificPaymentData>
</initiatePaymentRequest>

Example initiatePaymentResponse (with AuthorisedByProvider state):

<initiatePaymentResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <payment xsi:type="paymentWithPaymentAccount">
        <merchantID>B2BTestMerchant</merchantID>
        <shopID>AircashProviderShop</shopID>
        <paymentMethod>
            <key>443</key>
            <value>Aircash Voucher Deposit</value>
        </paymentMethod>
        <merchantTransactionID>hc-20230830-141855</merchantTransactionID>
        <paymentID>00981c2c-99e2-4fa2-830d-0b294544d063</paymentID>
        <userID>hc20230830141855</userID>
        <paymentProvider>
            <key>209</key>
            <value>Aircash</value>
        </paymentProvider>
        <amount currencyCode="EUR">20</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>80.121.151.158</userIP>
        <state>
            <id>5e9a4275-1c40-45c7-8406-130a2b9aef83</id>
            <definition>
                <key>13</key>
                <value>AuthorisedByProvider</value>
            </definition>
            <createdOn>2023-08-30T12:18:55.7080199Z</createdOn>
           <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderStatusCode</key>
                    <value>2</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>PaymentStateReasonID</key>
                    <value>1</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>false</isExecuted>
        <baseAmount currencyCode="EUR">20</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>OriginalVoucherISOCurrency</key>
                <value>EUR</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>OriginalVoucherValue</key>
                <value>20.00</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>CurrentVoucherValue</key>
                <value>20.00</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>5468</value>
            </detail>
        </paymentDetails>
    </payment>
</initiatePaymentResponse>

Example initiatePaymentResponse (with InitiatedByProvider state):

<initiatePaymentResponse xmlns=http://www.cqrpayments.com/PaymentProcessing xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance>
    <payment xsi:type="paymentWithPaymentAccount">
        <merchantID>B2BTestMerchant</merchantID>
        <shopID>AircashMockShop</shopID>
        <paymentMethod>
            <key>443</key>
            <value>Aircash Voucher Deposit</value>
        </paymentMethod>
        <merchantTransactionID>hc-20230918-112739</merchantTransactionID>
        <paymentID>d768c9d4-6afb-471e-9695-dc9b75391958</paymentID>
        <userID>hc20230918112739</userID>
        <paymentProvider>
            <key>209</key>
            <value>Aircash</value>
        </paymentProvider>
        <amount currencyCode="EUR">150</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>80.121.151.158</userIP>
        <state>
            <id>d2dcb35f-6909-457f-b5a4-63a39d43292a</id>
            <definition>
                <key>3</key>
                <value>InitiatedByProvider</value>
            </definition>
            <createdOn>2023-09-18T09:27:40.5616279Z</createdOn>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderStatusCode</key>
                    <value>1</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>PaymentStateReasonID</key>
                    <value>1</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>false</isExecuted>
        <baseAmount currencyCode="EUR">150</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderUserID</key>
                <value>ccc1b67f-c871-45ff-9226-81b9e84d07a0</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>OriginalVoucherISOCurrency</key>
                <value>EUR</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>OriginalVoucherValue</key>
                <value>150.00</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>CurrentVoucherValue</key>
                <value>150.00</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>7820</value>
            </detail>
        </paymentDetails>
    </payment>
</initiatePaymentResponse>

Example initiatePaymentResponse with error state InitiateErrorReportedByProvider: 

<initiatePaymentResponse xmlns=http://www.cqrpayments.com/PaymentProcessing xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance>
    <payment xsi:type="paymentWithPaymentAccount">
        <merchantID>B2BTestMerchant</merchantID>
        <shopID>AircashMockShop</shopID>
        <paymentMethod>
            <key>443</key>
            <value>Aircash Voucher Deposit</value>
        </paymentMethod>
        <merchantTransactionID>hc-20230915-142503</merchantTransactionID>
        <paymentID>2a9ae5ee-5d7d-4e5e-adcb-f4f95e307b75</paymentID>
        <userID>hc20230915142503</userID>
        <paymentProvider>
            <key>209</key>
            <value>Aircash</value>
        </paymentProvider>
        <amount currencyCode="EUR">10.2</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>80.121.151.158</userIP>
        <state>
            <id>25d9f9e5-ce26-4c66-bc8f-46385ae14386</id>
            <definition>
                <key>4</key>
                <value>InitiateErrorReportedByProvider</value>
            </definition>
            <createdOn>2023-09-15T12:25:03.4617214Z</createdOn>
            <description>Currency from the provider does not match that of the payment.</description>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                   <key>ProviderStatusCode</key>
                    <value>1</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>PaymentStateReasonID</key>
                    <value>1</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>false</isExecuted>
        <baseAmount currencyCode="EUR">10.2</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>OriginalVoucherISOCurrency</key>
                <value>EUR</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>OriginalVoucherValue</key>
                <value>150.00</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>CurrentVoucherValue</key>
                <value>150.00</value>
            </detail>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>7788</value>
            </detail>
        </paymentDetails>
    </payment>
</initiatePaymentResponse>

Example initiatePaymentResponse with error state InitiateRefusedByProvider:

<initiatePaymentResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <payment xsi:type="paymentWithPaymentAccount">
        <merchantID>B2BTestMerchant</merchantID>
        <shopID>AircashProviderShop</shopID>
        <paymentMethod>
            <key>443</key>
            <value>Aircash Voucher Deposit</value>
        </paymentMethod>
        <merchantTransactionID>hc-20230830-141527</merchantTransactionID>
        <paymentID>080a6b00-232f-4135-b910-c0dda399a99d</paymentID>
        <userID>hc20230830141527</userID>
        <paymentProvider>
            <key>209</key>
            <value>Aircash</value>
        </paymentProvider>
        <amount currencyCode="EUR">0</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>80.121.151.158</userIP>
        <state>
            <id>feaa1521-8749-4a17-bfd7-fb802491b89a</id>
            <definition>
                <key>550</key>
                <value>InitiateRefusedByProvider</value>
            </definition>
            <createdOn>2023-08-30T12:15:30.2342258Z</createdOn>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderResponseCode</key>
                    <value>4</value>
               </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderResponseMessage</key>
                    <value>coupon_already_used</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>PaymentStateReasonID</key>
                    <value>1</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>false</isExecuted>
        <baseAmount currencyCode="EUR">0</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>5466</value>
            </detail>
        </paymentDetails>
    </payment>
</initiatePaymentResponse>

<initiatePaymentResponse xmlns=http://www.cqrpayments.com/PaymentProcessing xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance>
    <payment xsi:type="paymentWithPaymentAccount">
        <merchantID>B2BTestMerchant</merchantID>
        <shopID>AircashMockShop</shopID>
        <paymentMethod>
            <key>443</key>
            <value>Aircash Voucher Deposit</value>
        </paymentMethod>
        <merchantTransactionID>hc-20230915-142408</merchantTransactionID>
        <paymentID>35ee2603-070d-445e-985d-5652e2f57cd9</paymentID>
        <userID>hc20230915142408</userID>
        <paymentProvider>
            <key>209</key>
            <value>Aircash</value>
        </paymentProvider>
        <amount currencyCode="EUR">10.1</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>80.121.151.158</userIP>
        <state>
            <id>213903a4-b3aa-44c7-8b4e-a4431bd0bb40</id>
            <definition>
                <key>550</key>
                <value>InitiateRefusedByProvider</value>
            </definition>
            <createdOn>2023-09-15T12:24:11.9291997Z</createdOn>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderResponseCode</key>
                    <value>13</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderResponseMessage</key>
                    <value>invalid_phone_number_format</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>PaymentStateReasonID</key>
                    <value>1</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>false</isExecuted>
        <baseAmount currencyCode="EUR">10.1</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>7787</value>
            </detail>
        </paymentDetails>
    </payment>
</initiatePaymentResponse>

Example initiatePaymentResponse with error state InitiateRequestProviderCommunicationErrorOccurred:

<initiatePaymentResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <payment xsi:type="paymentWithPaymentAccount">
        <merchantID>B2BTestMerchant</merchantID>
        <shopID>AircashProviderShop</shopID>
        <paymentMethod>
            <key>443</key>
            <value>Aircash Voucher Deposit</value>
        </paymentMethod>
        <merchantTransactionID>hc-20230831-105637</merchantTransactionID>
        <paymentID>489fb65e-155a-4e7b-9d66-5b2ec75cc330</paymentID>
        <userID>hc20230831105637</userID>
        <paymentProvider>
            <key>209</key>
            <value>Aircash</value>
        </paymentProvider>
        <amount currencyCode="EUR">0</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>80.121.151.158</userIP>
        <state>
            <id>131395e0-667a-45f0-8ae2-79ceed8f3062</id>
            <definition>
                <key>325</key>
                <value>InitiateRequestProviderCommunicationErrorOccurred</value>
            </definition>
            <createdOn>2023-08-31T08:56:57.3733945Z</createdOn>
            <description>Error occurred while processing payment communication for Payment[ID='48463489'].</description>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>PaymentStateReasonID</key>
                    <value>1</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>false</isExecuted>
        <baseAmount currencyCode="EUR">0</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>5615</value>
            </detail>
        </paymentDetails>
    </payment>
</initiatePaymentResponse>

The payment flow may include a notification as follows:

User approvalinitiatePaymentResponseNotification
no user approval necessaryAuthorizedByProviderno notification is sent to merchant
user approval necessaryInitiatedByProvidernotification is sent for state AuthorizedByProvider

Merchant approval

Once the payment has been moved to state AuthorisedByProvider, the merchant is expected to send an executePaymentAction request with either execute Payment (ID 95030) or refuse Payment (ID 8).

Example executePaymentAction request with action 95030 (Approved):

<executePaymentActionRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
                 <merchantID>{{merchant}}</merchantID>
    <shopID>{{shop}}</shopID>
               <paymentID>{{originalPaymentUniqueID}}</paymentID>
               <actionID>95030</actionID>
               <remark>Approved</remark>
</executePaymentActionRequest>

Example executePaymentAction request with action 8 (Reject):

<executePaymentActionRequest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="http://www.cqrpayments.com/PaymentProcessing">
                 <merchantID>{{merchant}}</merchantID>
    <shopID>{{shop}}</shopID>
               <paymentID>{{originalPaymentUniqueID}}</paymentID>
               <actionID>8</actionID>
               <remark>reject</remark>
</executePaymentActionRequest>

In the case of action 8, the payment will go to state RefusedByMerchant. No further communication with Aircash takes place.

Example excutePaymentAction response with state RefusedByMerchant:

<executePaymentActionResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <statusCode>1</statusCode>
    <actionResults>
        <result xsi:type="keyStringValuePair">
            <key>lastStateDefinition</key>
            <value>342</value>
        </result>
        <result xsi:type="keyStringValuePair">
            <key>PaymentStateReasonID</key>
            <value>1</value>
        </result>
    </actionResults>
</executePaymentActionResponse>

In the case of action iD 95030, a request is sent to Aircash and subsequently the payment will go to state DepositedByProvider, RefusedByProvider, DepositErrorReportedByProvider or DepositRequestSentToProviderCommunicationErrorOccurred.

StateDescription
DepositedByProviderA successful response has been received from Aircash. The payment was moved to DepositedByProvider state and it was returned in the executePaymentAction response.
'RefusedByProviderA refusal response such as "Coupon Already Used" is returned from Aircash. If available, error details are stored as ProviderResponseCode and ProviderResponseMessage state details and returned in the executePaymentAction response.
DepositErrorReportedByProviderAn error response is received from Aircash. If available, error message is stored as ProviderErrorResponseMessage and returned in the executePaymentAction response.
DepositRequestSentToProviderCommunicationErrorOccurredNo response was received from Aircash. If the executePaymentAction response will have this communication error state, it is advised to resend the executePaymentActionRequest.

Example executePaymentActionResponse with state DepositedByProvider:

<executePaymentActionResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <statusCode>0</statusCode>
    <actionResults>
        <result xsi:type="keyStringValuePair">
            <key>lastStateDefinition</key>
            <value>29</value>
        </result>
        <result xsi:type="keyStringValuePair">
            <key>ProviderTransactionID</key>
            <value>6920492708414476</value>
        </result>
    </actionResults>
</executePaymentActionResponse>

Example executePaymentActionResponse with state RefusedByProvider:

<executePaymentActionResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <statusCode>0</statusCode>
    <actionResults>
        <result xsi:type="keyStringValuePair">
            <key>lastStateDefinition</key>
            <value>100</value>
        </result>
        <result xsi:type="keyStringValuePair">
            <key>ProviderResponseCode</key>
            <value>4</value>
        </result>
        <result xsi:type="keyStringValuePair">
            <key>ProviderResponseMessage</key>
            <value>coupon_already_used</value>
        </result>
        <result xsi:type="keyStringValuePair">
            <key>PaymentStateReasonID</key>
            <value>1</value>
        </result>
    </actionResults>
</executePaymentActionResponse>

Example executePaymentActionResponse with state DepositErrorReportedByProvider:

<executePaymentActionResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <statusCode>0</statusCode>
    <actionResults>
        <result xsi:type="keyStringValuePair">
            <key>lastStateDefinition</key>
            <value>152</value>
        </result>
        <result xsi:type="keyStringValuePair">
            <key>ProviderErrorResponseCode</key>
            <value>1</value>
        </result>
        <result xsi:type="keyStringValuePair">
            <key>ProviderErrorResponseMessage</key>
            <value>invalid_partner_id</value>
        </result>
        <result xsi:type="keyStringValuePair">
            <key>PaymentStateReasonID</key>
            <value>1</value>
        </result>
    </actionResults>
</executePaymentActionResponse>

Example executePaymentActionResponse with state DepositRequestSentToProviderCommunicationErrorOccurred:

<executePaymentActionResponse xmlns="http://www.cqrpayments.com/PaymentProcessing" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <statusCode>1</statusCode>
    <actionResults>
        <result xsi:type="keyStringValuePair">
            <key>lastStateDefinition</key>
            <value>353</value>
        </result>
        <result xsi:type="keyStringValuePair">
            <key>PaymentStateReasonID</key>
            <value>1</value>
        </result>
    </actionResults>
</executePaymentActionResponse>

Notifications

A notification for state AuthorisedByProvider is only sent if the payment moved from state InitiatedByProvider to state AuthorisedByProvider, or in other words, when the payment was approved by the user in the Aircash app.

Example handlePaymentStateChangedNotificationRequest for state AuthorisedByProvider:

<?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="http://www.cqrpayments.com/PaymentProcessing"
	         xsi:type="paymentWithPaymentAccount">
		<merchantID>B2BTestMerchant</merchantID>
		<shopID>AircashProviderUserAuthShop</shopID>
		<paymentMethod>
			<key>443</key>
			<value>Aircash Voucher Deposit</value>
		</paymentMethod>
		<merchantTransactionID>hc-20230912-193646</merchantTransactionID>
		<paymentID>f446499f-630f-4836-b267-4a2bfb64197e</paymentID>
		<userID>hc20230912193646</userID>
		<paymentProvider>
			<key>209</key>
			<value>Aircash</value>
		</paymentProvider>
		<amount currencyCode="EUR">25.0000</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>80.121.151.158</userIP>
		<state>
			<id>6e74da39-31cf-4fdb-9211-93534279c9d2</id>
			<definition>
				<key>13</key>
				<value>AuthorisedByProvider</value>
			</definition>
			<createdOn>2023-09-12T17:37:15.2370246Z</createdOn>
			<paymentStateDetails>
				<detail xsi:type="keyStringValuePair">
					<key>ProviderStatusCode</key>
					<value>2</value>
				</detail>
				<detail xsi:type="keyIntValuePair">
					<key>PaymentStateReasonID</key>
					<value>1</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>false</isExecuted>
		<baseAmount currencyCode="EUR">25.0000</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>7055</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderUserID</key>
				<value>4bf0b028-cbb1-447d-9c19-7197bbf5e023</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>OriginalVoucherISOCurrency</key>
				<value>EUR</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>OriginalVoucherValue</key>
				<value>25.00</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>CurrentVoucherValue</key>
				<value>25.00</value>
			</detail>
		</paymentDetails>
	</payment>
</handlePaymentStateChangedNotificationRequest>

Example handlePaymentStateChangedNotificationRequest for state Expired:

<?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="http://www.cqrpayments.com/PaymentProcessing"
	         xsi:type="paymentWithPaymentAccount">
		<merchantID>B2BTestMerchant</merchantID>
		<shopID>AircashMockShop</shopID>
		<paymentMethod>
			<key>443</key>
			<value>Aircash Voucher Deposit</value>
		</paymentMethod>
		<merchantTransactionID>905ee7f9-b0af-433c-a156-f3cde5af8c58</merchantTransactionID>
		<paymentID>9f5209f5-5b91-4a0d-9ee9-def5850984ac</paymentID>
		<userID>dbeff4a5-c481-4fa7-a45d-cf7495</userID>
		<paymentProvider>
			<key>209</key>
			<value>Aircash</value>
		</paymentProvider>
		<amount currencyCode="EUR">150.0000</amount>
		<creationType>
			<key>1</key>
			<value>User</value>
		</creationType>
		<userIP>127.0.0.1</userIP>
		<state>
			<id>ce8c441a-04c0-44e5-8aa5-51c4e86dd31e</id>
			<definition>
				<key>102</key>
				<value>Expired</value>
			</definition>
			<createdOn>2023-10-04T14:34:36.963</createdOn>
			<paymentStateDetails>
				<detail xsi:type="keyIntValuePair">
					<key>PaymentStateReasonID</key>
					<value>1</value>
				</detail>
			</paymentStateDetails>
		</state>
		<isExecuted>false</isExecuted>
		<baseAmount currencyCode="EUR">150.0000</baseAmount>
		<paymentDetails>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderExternalID</key>
				<value>9200</value>
			</detail>
			<detail xsi:type="keyStringValuePair">
				<key>ProviderUserID</key>
				<value>ccc1b67f-c871-45ff-9226-81b9e84d07a0</value>
			</detail>
		</paymentDetails>
	</payment>
</handlePaymentStateChangedNotificationRequest>

Testing

Besides provider testing, PXP also supports merchant testing will be supported with a merchant mock. Some states that are difficult or impossible to test with provider, can be tested when the merchant mock is used.

Testing stateInstructions
InitiateRefusedByProviderUse amount 10.1
InititateErrorReportedByProviderUse amount 10.2
InitiateRequestProviderCommunicationErrorOccurredUse amount 10.5
InitiatedByProviderUse amount 10.4

Any other amount sent to merchant mock will result in the payment going to state AuthorisedByProvider.

Sample initiatePaymentRequest:

<initiatePaymentRequest xmlns=http://www.cqrpayments.com/PaymentProcessing xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance xmlns:xsd=http://www.w3.org/2001/XMLSchema>
    <merchantID>{{merchant}}</merchantID>
    <shopID>{{shop}}</shopID>
    <merchantTransactionID>{{merchantTransactionID}}</merchantTransactionID>
    <paymentMethodID>443</paymentMethodID>
    <amount currencyCode="EUR">10.3</amount>
    <userID>{{newUserID}}</userID>
    <userData>
        <username>{{newUserName}}</username>
        <firstname>John</firstname>
        <lastname>Doe</lastname>
        <currencyCode>EUR</currencyCode>
        <languageCode>EN</languageCode>
        <email>{{newUserEmail}}</email>
        <address>
            <street>196 Rus St</street>
            <houseNumber>1b</houseNumber>
            <postalCode>7582</postalCode>
            <city>Kuils River</city>
            <state>WC</state>
            <countryCode2>ZA</countryCode2>
            <telephoneNumber>270839661769</telephoneNumber>
        </address>
        <dateOfBirth>1980-10-10T00:00:00</dateOfBirth>
        <gender>Male</gender>
    </userData>
    <userIP>80.121.151.158</userIP>
    <userSessionID>t02d03hwaxkrl5gmabcypwmm</userSessionID>
    <creationTypeID>1</creationTypeID>
    <specificPaymentData>
        <data xsi:type="keyStringValuePair">
            <key>PaymentDescription</key>
            <value>test</value>
        </data>
        <data xsi:type="keyStringValuePair">
            <key>SerialNumber</key>
            <value>7456796114213850</value>
        </data>
    </specificPaymentData>
</initiatePaymentRequest>

Updated 11 months ago