Aircash Marketplace Deposit
The Aircash Marketplace allows creating a deposit from Aircash´s marketplace page directly to the merchant.
The following method IDs are covered in this section:
ID | Name | Credit/Debit State |
---|---|---|
444 | Aircash Marketplace Deposit | DepositedByProvider (29) |
Payment method interaction type: Notification from External Payment Provider (see Interaction Types).
Flow
Note: this diagram is simplied and may be missing some data that is exchanged between Aircash, PXP and the merchant.
![](https://files.readme.io/2ae05e5-swimlanes-e3b393edea43be8ad786c2faddb1ad64.png)
The following will happen:
- Aircash user will go to the marketplace section within the Aircash App
- Aircash user will choose for which merchant brand/label he/she intends to deposit
- Aircash will create unique partnerID/merchantID for each brand - at PXP this relates to a merchant/shop combination
- Aircash user will enter his eMail address
- Aircash will send CheckPlayer Call to PXP
- PXP will call merchant with getNewManualPaymentDetails request (see below)
- Merchant will perform an account lookup based on the merchantID and eMail and other data sent in the request
- Merchant will send getNewManualPaymentDetails response indicating if the user exists or not.
If the user exists, merchant will pass userdata and userLimit. - PXP will create a user if it is not yet existing at PXP
- PXP will send CheckPlayer response to Aircash
- Aircash will perform name verification check
- Aircash will allow user to deposit and Aircash will validate the amount against max allowed deposit value passed in the CheckPlayer response
- Aircash will call PXP with CreateAndConfirmPayment request
- PXP will create a payment in their system (and assign payment details including a GUID as the paymentID/merchantTransactionID)
- PXP will call the merchant to approve the payment
- Merchant to respond to PXP
- PXP to update the payment status
- PXP to send CreateAndConfirmPayment response to Aircash
Redirect Integration
Currently not supported.
Backend2BackendIntegration User Lookup
Before the payment is created, Aircash will send a CheckPlayer request to find the user - this results in PXP sending a getManualPaymentDetailRequest to the merchant.
The following details will be included in the getNewManualPaymentDetailsRequest:
merchantID | MerchantID |
paymentMethodID | defaults to 444 (Aircash Marketplace Deposit) |
The user´s eMail address | |
dateOfBirth | The user`s date of birth |
firstName | The user´s first name |
lastName | The user´s last name |
currencyID | The user´s currency. |
providerUserID | The user´s userID at Aircash. |
The following details should be returned in the getNewManualPaymentDetailsResponse passed by the merchant to PXP.
code | 0 (User found), 2 (User not found), 3 (User found, but deposit cannot be accepted, 4 (User found but deposit not allowed due to currency mismatch9 |
userID | The user´s userID |
username (within userDetails) | The user´s username value. |
firstname (within userDetails) | The user´s first name. |
lastname (within userDetails) | The user´s last name. |
email (within userDetails) | The user´s eMail address |
dateOfBirth (within userDetails) | The user´s date of birth |
maxLimit (within paymentDetails) | The user´s max limit for the payment. Full amount in the limit currency. |
limitCurrency (within paymentDetails) | The user´s limit currency. |
Example getNewManualPaymentDetailsRequest:
<getNewManualPaymentDetailsRequest xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance>
<merchantID>B2BTestMerchant</merchantID>
<paymentMethodID>444</paymentMethodID>
<userID xsi:nil="true" />
<username xsi:nil="true" />
<email>[email protected]</email>
<languageCode xsi:nil="true" />
<dateOfBirth>1980-01-01T00:00:00</dateOfBirth>
<firstName>Chloe</firstName>
<lastName>Ko</lastName>
<telephoneNumber xsi:nil="true" />
<currencyID>EUR</currencyID>
<providerUserID>4bf0b028-cbb1-447d-9c19-7197bbf5e023</providerUserID>
</getNewManualPaymentDetailsRequest>
Request details
The getManualPaymentDetailsRequest is using a standard format.
New details are the providerUserID with the AircashUserID and the paymentMethodID being 444 (Aircash Marketplace Deposit).
Example getNewManualPaymentDetailsResponse - user not found:
<getNewManualPaymentDetailsResponse xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance>
<result>
<merchantTransactionID xsi:nil="true" xmlns=http://www.cqrpayments.com/PaymentProcessing />
<userDetails xmlns=http://www.cqrpayments.com/PaymentProcessing>
<username xsi:nil="true" />
<firstname xsi:nil="true" />
<lastname xsi:nil="true" />
<currencyCode xsi:nil="true" />
<languageCode xsi:nil="true" />
<email xsi:nil="true" />
<address xsi:nil="true" />
<identificationNumber xsi:nil="true" />
<identificationNumberType xsi:nil="true" />
<drivingLicenseNumber xsi:nil="true" />
<drivingLicenseIssuingState xsi:nil="true" />
<userStatus xsi:nil="true" />
</userDetails>
</result>
<status>
<code xmlns=http://www.cqrpayments.com/PaymentProcessing>2</code>
<description xmlns=http://www.cqrpayments.com/PaymentProcessing>User not found</description>
<details xmlns=http://www.cqrpayments.com/PaymentProcessing />
</status>
</getNewManualPaymentDetailsResponse>
Example getNewManualPaymentDetailsResponse - user found:
<getNewManualPaymentDetailsResponse xmlns:xsd=http://www.w3.org/2001/XMLSchema xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance>
<result>
<userID xmlns=http://www.cqrpayments.com/PaymentProcessing>ho-chun.ko20</userID>
<merchantTransactionID xsi:nil="true" xmlns=http://www.cqrpayments.com/PaymentProcessing />
<userDetails xmlns=http://www.cqrpayments.com/PaymentProcessing>
<username>ChloeKo</username>
<firstname>Chloe</firstname>
<lastname>Ko</lastname>
<currencyCode xsi:nil="true" />
<languageCode xsi:nil="true" />
<email>[email protected]</email>
<address xsi:nil="true" />
<dateOfBirth>1978-12-28T00:00:00</dateOfBirth>
<identificationNumber xsi:nil="true" />
<identificationNumberType xsi:nil="true" />
<drivingLicenseNumber xsi:nil="true" />
<drivingLicenseIssuingState xsi:nil="true" />
<userStatus xsi:nil="true" />
</userDetails>
<paymentDetails xmlns=http://www.cqrpayments.com/PaymentProcessing>
<detail xsi:type="keyDecimalValuePair">
<key>maxLimit</key>
<value>1200.00</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>limitCurrency</key>
<value>EUR</value>
</detail>
</paymentDetails>
</result>
<status>
<code xmlns=http://www.cqrpayments.com/PaymentProcessing>0</code>
<description xmlns=http://www.cqrpayments.com/PaymentProcessing />
<details xmlns=http://www.cqrpayments.com/PaymentProcessing />
</status>
</getNewManualPaymentDetailsResponse>
The merchant may pass the following response codes back to PXP.
responseStatus.Code | Description |
---|---|
0 | User found |
2 | User not found |
3 | User found but deposit cannot be accepted |
4 | User found but deposit not allowed due to currency mismatch |
Error handling on CheckPlayer response
Additional error code can be passed to provider Aircash. Please check with PXP for information.
{
"isPlayer": false,
"error": {
"errorCode": 2,
"errorMessage": "User not found"
},
"parameters": null
}
When the merchant returns status.code = 3 and status.description = "User found but deposit cannot be accepted", PXP will send the following CheckPlayer response to Aircash:
{
"isPlayer": false,
"error": {
"errorCode": 3,
"errorMessage": "User found but deposit cannot be accepted"
},
"parameters": null
}
XSD
All the basic types are included in the main XSD, see here.
Backend2BackendIntegration Payment Creation
After receiving a CreateAndConfirmPayout request from Aircash, a payment will be created and a request is sent to the merchant backend. The merchant now has the chance to accept or decline the payment.
Example handlePaymentStateChangedNotificationRequest (Created):
<?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>B2BTestMerchant</merchantID>
<shopID>AircashProviderShop</shopID>
<paymentMethod>
<key>444</key>
<value>Aircash Marketplace Deposit</value>
</paymentMethod>
<merchantTransactionID>f02b9ae6-c3ba-45f8-a6d7-20b8958c4570</merchantTransactionID>
<paymentID>61f30680-6fca-4c1a-8031-d18295c8cb4e</paymentID>
<userID>ho-chun.ko20</userID>
<paymentProvider>
<key>209</key>
<value>Aircash</value>
</paymentProvider>
<amount currencyCode="EUR">111</amount>
<shopFee currencyCode="EUR">0</shopFee>
<creationType>
<key>6</key>
<value>Provider</value>
</creationType>
<userIP>127.0.0.1</userIP>
<state>
<id>0a8622a3-74a9-4836-96b2-5f827ebeae77</id>
<definition>
<key>232</key>
<value>Created</value>
</definition>
<createdOn>2023-10-11T20:53:27.9024614Z</createdOn>
<paymentStateDetails>
<detail xsi:type="keyIntValuePair">
<key>PaymentStateReasonID</key>
<value>1</value>
</detail>
</paymentStateDetails>
</state>
<isExecuted>false</isExecuted>
<baseAmount currencyCode="EUR">111</baseAmount>
<paymentDetails>
<detail xsi:type="keyDecimalValuePair">
<key>BaseShopFeeAmount</key>
<value>0</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>BaseShopFeeCurrencyCode</key>
<value>EUR</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderExternalID</key>
<value>10349</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderTransactionID</key>
<value>56573277-46e6-4c7e-949e-101e917e21cc</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderUserID</key>
<value>4bf0b028-cbb1-447d-9c19-7197bbf5e023</value>
</detail>
</paymentDetails>
</payment>
</handlePaymentStateChangedNotificationRequest>
Example handlePaymentStateChangedNotificationResponse (successful):
<?xml version="1.0" encoding="utf-16"?>
<handlePaymentStateChangedNotificationResponse xmlns:xsd=http://www.w3.org/2001/XMLSchema
xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance>
<resultCode>
<key xmlns=http://www.cqrpayments.com/PaymentProcessing>0</key>
<value
xmlns=http://www.cqrpayments.com/PaymentProcessing>ProcessedSuccessfully</value>
</resultCode>
<resultMessage>Request processed by mock service</resultMessage>
<details xsi:nil="true"/>
</handlePaymentStateChangedNotificationResponse>
Response Field | Available Values | Description |
---|---|---|
resultCode.key | 0 and other values, see below | Default PaymentStateChangedHandling result code, values see below |
resultCode.value | See table below | Description passed to Aircash, but not used for display to customer. |
resultMessage | Optional detail that is not passed to Aircash | Optional detail that is not passed to Aircash |
The following resultCodes are available for the handlePaymentStateChangedNotification response:
ResultCode | Description |
---|---|
0 | Processed Successful |
3 | RefusedByRiskManagement |
6 | UserAccountBlocked |
7 | PaymentAccountDisabled |
8 | PaymentAccountProblem |
9 | RefusedByLimitCheck |
15 | BlockedByMerchannt |
Example handlePaymentStateChangedNotificationResponse (RefusedByLimitCheck):
<?xml version="1.0" encoding="utf-16"?>
<handlePaymentStateChangedNotificationResponse xmlns:xsd=http://www.w3.org/2001/XMLSchema
xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance>
<resultCode>
<key xmlns=http://www.cqrpayments.com/PaymentProcessing>9</key>
<value
xmlns=http://www.cqrpayments.com/PaymentProcessing>RefusedByLimitCheck</value>
</resultCode>
<resultMessage>anything</resultMessage>
<details xsi:nil="true"/>
</handlePaymentStateChangedNotificationResponse>
Example handlePaymentStateChangedNotificationResponse (BlockedByMerchant):
<?xml version="1.0" encoding="utf-16"?>
<handlePaymentStateChangedNotificationResponse xmlns:xsd=http://www.w3.org/2001/XMLSchema
xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance>
<resultCode>
<key xmlns=http://www.cqrpayments.com/PaymentProcessing>15</key>
<value
xmlns=http://www.cqrpayments.com/PaymentProcessing>BlockedByMerchant</value>
</resultCode>
<resultMessage>anything</resultMessage>
<details xsi:nil="true"/>
</handlePaymentStateChangedNotificationResponse>
Example handlePaymentStateChangedNotificationResponse (Technical error occurred):
<?xml version="1.0" encoding="utf-16"?>
<handlePaymentStateChangedNotificationResponse xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<resultCode>
<key xmlns="http://www.cqrpayments.com/PaymentProcessing">400</key>
<value xmlns="http://www.cqrpayments.com/PaymentProcessing">TechnicalError</value>
</resultCode>
<resultMessage>Technical error occurred</resultMessage>
<details xsi:nil="true" />
</handlePaymentStateChangedNotificationResponse>
Once the payment has been accepted by the merchant, it will be moved to the final state DepositedByProvider and a notification will be sent to the merchant.
Example handlePaymentStateChangedNotificationRequest (DepositedByProvider)
<?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>AircashProviderShop</shopID>
<paymentMethod>
<key>444</key>
<value>Aircash Marketplace Deposit</value>
</paymentMethod>
<merchantTransactionID>853915eb-d865-4983-b82c-019580af7453</merchantTransactionID>
<paymentID>ebfdfba6-3855-4a30-9da5-93c36bfd1ca1</paymentID>
<userID>hc4</userID>
<paymentProvider>
<key>209</key>
<value>Aircash</value>
</paymentProvider>
<amount currencyCode="EUR">1.0000</amount>
<shopFee currencyCode="EUR">0.0000</shopFee>
<creationType>
<key>6</key>
<value>Provider</value>
</creationType>
<userIP>127.0.0.1</userIP>
<state>
<id>f6048dde-0b27-49a4-99b3-0f81e0aed975</id>
<definition>
<key>29</key>
<value>DepositedByProvider</value>
</definition>
<createdOn>2023-10-12T10:20:40.417</createdOn>
<paymentStateDetails xsi:nil="true"/>
</state>
<isExecuted>true</isExecuted>
<baseAmount currencyCode="EUR">1.0000</baseAmount>
<paymentDetails>
<detail xsi:type="keyDecimalValuePair">
<key>BaseShopFeeAmount</key>
<value>0.0000</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>BaseShopFeeCurrencyCode</key>
<value>EUR</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderExternalID</key>
<value>10690</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderTransactionID</key>
<value>01bdd922-6588-407d-8fac-3fc501372871</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderUserID</key>
<value>4bf0b028-cbb1-447d-9c19-7197bbf5e023</value>
</detail>
</paymentDetails>
</payment>
</handlePaymentStateChangedNotificationRequest>
Notifications
The standard notification mechanism is used to notify the merchant of the final state DepositedByProvider.
Once the payment has been accepted by the merchant, it will be moved to the final state DepositedByProvider and a notification will be sent to the merchant.
Example handlePaymentStateChangedNotificationRequest (DepositedByProvider)
<?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>AircashProviderShop</shopID>
<paymentMethod>
<key>444</key>
<value>Aircash Marketplace Deposit</value>
</paymentMethod>
<merchantTransactionID>853915eb-d865-4983-b82c-019580af7453</merchantTransactionID>
<paymentID>ebfdfba6-3855-4a30-9da5-93c36bfd1ca1</paymentID>
<userID>hc4</userID>
<paymentProvider>
<key>209</key>
<value>Aircash</value>
</paymentProvider>
<amount currencyCode="EUR">1.0000</amount>
<shopFee currencyCode="EUR">0.0000</shopFee>
<creationType>
<key>6</key>
<value>Provider</value>
</creationType>
<userIP>127.0.0.1</userIP>
<state>
<id>f6048dde-0b27-49a4-99b3-0f81e0aed975</id>
<definition>
<key>29</key>
<value>DepositedByProvider</value>
</definition>
<createdOn>2023-10-12T10:20:40.417</createdOn>
<paymentStateDetails xsi:nil="true"/>
</state>
<isExecuted>true</isExecuted>
<baseAmount currencyCode="EUR">1.0000</baseAmount>
<paymentDetails>
<detail xsi:type="keyDecimalValuePair">
<key>BaseShopFeeAmount</key>
<value>0.0000</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>BaseShopFeeCurrencyCode</key>
<value>EUR</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderExternalID</key>
<value>10690</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderTransactionID</key>
<value>01bdd922-6588-407d-8fac-3fc501372871</value>
</detail>
<detail xsi:type="keyStringValuePair">
<key>ProviderUserID</key>
<value>4bf0b028-cbb1-447d-9c19-7197bbf5e023</value>
</detail>
</paymentDetails>
</payment>
</handlePaymentStateChangedNotificationRequest>
Testing
Testing can be supported with a merchant mock. This omits the getNewManualPaymentDetailsRequest sent to merchant. For this the merchant mock needs to be configured for some merchant/shop.
Email used to get specific merchant MOCK responses for user look up:
User found -> 0 {whatever}[email protected]
User not found -> 2 {whatever}[email protected]
Amount used to get specific merchant MOCK responses for created payment:
Blocked by merchant -> NotifyPaymentStateBlockedByMerchant 15.00
Refused by limit check -> NotifyPaymentStateRefusedByMerchant 46.00
Timeout handling
Time-out of the merchant response to the handlePaymentStateChangedNotificationRequest (Created state):
- In case of time-out of the merchant response, the payment goes to RefusedByMerchant state and the appropriate error response is returned to Aircash. Please note that PXP does not notify merchant by default about RefusedByMerchant state - this can be configured on request.
- If provider Aircash sends a duplicate request with the same transactionID - no new payment is created at PXP, merchant is not notified, error response is returned back to the provider.
- If provider sends new request with the same details but new transactionID - new payment with new MerchantTransactionID will be created by PXP and merchant will be notified about new payment accordingly.
Time-out of the provider response
If a payment already has been accepted by the merchant and thus the payment is having DepositedByProvider state, and Aircash sends PXP a duplicate request, then PXP does not notify the merchant again but immediately returns a successful response to the provider.
Updated 7 months ago