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.

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)
email	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.

Flow

Redirect Integration

Backend2BackendIntegration User Lookup

🚧Request details

Error handling on CheckPlayer response

XSD

Backend2BackendIntegration Payment Creation

Notifications

Testing

Timeout handling

🚧
Request details