# Payment API (Compliant with Payment Services Directive for UK customers)
source: https://developer.mastercard.com/cross-border-services/documentation/api-ref/psd2-uk-payment-api/index.md
You can use this API to submit a payment transaction to transfer fund to a cross-border recipient.
If you opt-in for quote confirmation services, remember to confirm the quote before initiating the payment request.
Look at the [Payment](https://developer.mastercard.com/cross-border-services/documentation/use-cases/index.md) use cases for details on how to use the payment API for a cross border fund transfer solution.
## Environment Domains {#environment-domains}
* Sandbox
* MTF
* Production
```Sandbox
https://sandbox.api.xbs.mastercard.uk/send/v1/partners/{partner-id}/crossborder/payment
```
```MTF
https://mtf.api.xbs.mastercard.uk/send/v1/partners/{partner-id}/crossborder/payment
```
```Production
https://api.xbs.mastercard.uk/send/v1/partners/{partner-id}/crossborder/payment
```
## API {#api}
[**Open Specification**](https://static.developer.mastercard.com/content/cross-border-services/swagger/cross-border-uk-swagger.yaml)
Alternatively, here is a tabular view of the request/ response parameter:
[Payment_Specifications.pdf](https://static.developer.mastercard.com/content/cross-border-services/uploads/Payment_Specifications.pdf) (1MB)
API Reference: `GET /send/v1/partners/{partner-id}/crossborder/payment`
Note: In order to provide ease of processing and to avoid any potential keying errors, when a Quote is utilized and the Quote Proposal ID information is provided for payment initiation, the quote transaction details (sending/receiving accounts, amounts, currencies, etc.) are used to fill the payment request.
* **Formats supported** : XML/ JSON
* **HTTP Version**: 1.0/ 1.1
* **Required HTTP header parameters** :
content-type : Format of the inbound content being submitted. example: application/json
content-length: Length of the inbound content body in octets.
Accept: Format of the expected response must be provided in this header field. Example - application/json
## API Convention {#api-convention}
Take a look at the [API Conventions](https://developer.mastercard.com/cross-border-services/documentation/api-basics/api-conventions/index.md) for general guidelines.
## Payload Encryption {#payload-encryption}
All the request payload sent by you to Mastercard must be encrypted. And you will need to decrypt the payload sent by Mastercard.
For more detailed information on payload **Encryption/ Decryption** , please see [here](https://developer.mastercard.com/cross-border-services/documentation/api-ref/encryption/index.md)
## Sandbox Testing {#sandbox-testing}
You can make API calls to the Sandbox server from your application code using the [tutorials](https://developer.mastercard.com/cross-border-services/documentation/tutorials/index.md), which involves creating a Mastercard Developers project and using the Sandbox keys to generate the required Authorization Header.
Tip: During the onboarding process, Mastercard will assign a registered partner ID to test in the higher environments (MTF Test and Production). This partner ID will not be able to access the sandbox environment, but the customer can still access sandbox by using the non-registered partner ID.
Any correctly formatted partner ID can be used in the sandbox. As a best practice, use the first 15 digits of your institution's name (alphanumeric and/or special characters, no spaces) as the Partner_ID.
For testing in sandbox, please use unique transaction_reference on each run. Note: The sandbox does not return parameters unique to a specific Customer; such as pricing, limits, and corridor-specific data requirements, but allows you to test general call structure and responses outside of the production environment. After sandbox testing is completed, Customers meeting the eligibility requirements will be assigned a project manager to do integrated testing in the test environment that has been configured to include requested receiving corridors, current foreign exchange rates, and fixed and variable fees specific to the Customer.
### Sandbox Test cases {#sandbox-test-cases}
The Sandbox server returns simulated, static responses. You can use the following test cases to produce specific responses in sandbox.
#### Payment with Quote {#payment-with-quote}
| Status | Test Case | Action |
|-----------------------------------------|-----------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Success | Payment with Quote - responds with successful payment | 1. Send a Quote using 'transaction_reference' number starting with '09' 2. Send a Payment using the same 'transaction_reference' and the proposal ID from the quote response. |
| Success | Payment with Quote - responds with successful payment ( URIs not provided in quote) | 1. Send a Quote using 'transaction_reference' number starting with '09' 2. Send a Payment using the same 'transaction_reference' and the proposal ID from the quote response. |
| Pending | Payment with Quote- responds with pending payment | 1. Send a Quote using 'transaction_reference' number starting with '06' 2. Send a Payment using the same 'transaction_reference' and the proposal ID from the quote response and recipient_account_uri's last 6 digits as '10####' (# is not literal but can be any number). |
| Pending | Payment with Quote- responds with pending payment (URIs not provided in quote) | 1. Send a Quote using 'transaction_reference' number starting with '06' 2. Send a Payment using the same 'transaction_reference' and the proposal ID from the quote response and recipient_account_uri's last 6 digits as '10####' (# is not literal but can be any number). |
| Rejected | Payment with Quote - responds with rejected payment | 1. Send a Quote using 'transaction_reference' number starting with '04' 2. Send a Payment using the same 'transaction_reference' and the proposal ID from the quote response and recipient_account_uri's last 6 digits as '10####' (# is not literal but can be any number). |
| Rejected | Payment with Quote - responds with rejected payment (URIs not provided in quote) | 1. Send a Quote using 'transaction_reference' number starting with '04' 2. Send a Payment using the same 'transaction_reference' and the proposal ID from the quote response and recipient_account_uri's last 6 digits as '10####' (# is not literal but can be any number). |
| Rejected with specific error | Payment with Quote - responds with rejected payment with specific error code | 1. Send a Quote using 'transaction_reference' number starting with '2' and ending with the desired error code. For example: Transaction reference '2XXXXXXXX130105' will REJECT payment and return 130105 error code in the payment response. 2. Send a Payment using the 'proposal_id' from the quote. |
| Rejected- Can be resubmitted | 150001 System Error: Payment with Quote is resubmitted successfully | 1. Send a Quote using 'transaction_reference' number starting with '11S' and ends in '501'. For example: Transaction reference '11SXXXXXXXXXX501' will return a successful response. 2. Send a Payment using the 'transaction_reference' and 'proposal_id' (response) from the above quote request in step 1. The sandbox will return Pending status with Ambiguous Stage. 3. Resubmit the payment using the same 'transaction_reference' after 10 mins from the payment request with same input parameters. Transaction will be processed with status "Success". Note -- For the sandbox environment to simulate the desired responses, please resubmit the payment (step 3) after 10 minutes from the payment request (step 2) and within 30 minutes after the initial quote call (step 1). |
| Rejected - Resubmitted request rejected | 150001 System Error: Payment with Quote is resubmitted with different parameters and rejected | 1. Send a Quote using 'transaction_reference' number starting with '11S' and ends in '501'. For example: Transaction reference '11SXXXXXXXXXX501' will return a successful response. 2. Send a Payment using the 'proposal_id' from the above quote request in step 1. The sandbox will return Pending status with Ambiguous Stage. 3. Resubmit the payment using the same 'transaction_reference' and different input parameters(like different value for sender_account_uri. ) Transaction will be rejected with 82000 error code |
**Note** : For test scenarios to make a Quote API call, please look at the **Sandbox Test cases** section [here](https://developer.mastercard.com/cross-border-services/documentation/api-ref/quotes-api/index.md)
#### Payment without Quote {#payment-without-quote}
| Status | Test Case | Action |
|-----------------------------------------|------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Success | Payment (forward with fees included) - responds with successful payment | 1.Send Payment using 'transaction_reference' number starting with '09' 2. Make sure to pass the paymentrequest.fx_type.forward object with fees-included =true in the request. |
| Success | Payment (forward with fees not included) - responds with successful payment | 1.Send Payment using 'transaction_reference' number starting with '09' 2. Make sure to pass the paymentrequest.fx_type.forward object with fees-included = false in the request. |
| Success | Payment (reverse) - responds with successful payment | 1. Send Payment using 'transaction_reference' number starting with '09' 2. Make sure to pass the paymentrequest.fx_type.reverse object in the request. |
| Pending | Payment (forward with fees included) - responds with pending payment | 1. Send a Payment using 'transaction_reference' number starting with '06' and recipient_account_uri's last 6 digits as '10####' (# is not literal but can be any number). 2. Make sure to pass the paymentrequest.fx_type.forward object with fees-included =true in the request. |
| Pending | Payment (forward with fees not included) - responds with pending payment | 1. Send a Payment using 'transaction_reference' number starting with '06' and recipient_account_uri's last 6 digits as '10####' (# is not literal but can be any number). 2. Make sure to pass the paymentrequest.fx_type.forward object with fees-included =false in the request. |
| Pending | Payment (reverse) - responds with pending payment | 1. Send a Payment using 'transaction_reference' number starting with '06' and recipient_account_uri's last 6 digits as '10####' (# is not literal but can be any number). 2. Make sure to pass the paymentrequest.fx_type.reverse object in the request. |
| Rejected | Payment (forward with fees included) - responds with rejected payment | Send a Payment using 'transaction_reference' number starting with '04' and recipient_account_uri's last 6 digits as '10####' (# is not literal but can be any number). |
| Rejected with specific error | Payment - responds with rejected payment with specific error code | Send a Payment using 'transaction_reference' number starting with '2' and ending with the desired error code. For example: Transaction reference '2XXXXXXXX130105' will REJECT payment and return 130105 error code in response |
| Rejected - Can be resubmitted | 150001 System Error: Payment is resubmitted successfully | 1. Send a Payment using 'transaction_reference' number starting with '11S' and ends with '501'. For example: Transaction reference '11SXXXXXXXXXX501'' . The sandbox will return Pending status with Ambiguous Stage. 2. Resubmit the payment using the same 'transaction_reference' after 10 min with same input parameters. Note -- For the sandbox environment to simulate the desired responses, please resubmit the payment (step 2) after 10 minutes from step 1 and within 30 minutes from the initial payment request (step 1). |
| Rejected - Resubmitted request rejected | 150001 System Error: Payment is resubmitted with different parameters and rejected | 1. Send a Payment using 'transaction_reference' number starting with '11S' and ends with '501'. For example: Transaction reference '11SXXXXXXXXXX501'' . The sandbox will return Pending status with Ambiguous Stage. 2. Resubmit the payment using the same 'transaction_reference' and different parameters (like different value for sender_account_uri. ) Transaction will be rejected with 82000 error code. |
### Sandbox Test cases for Wires {#sandbox-test-cases-for-wires}
The Sandbox server returns simulated, static responses. For customers who are interested or enabled to instruct wire transactions, can use the following test cases to produce specific responses in sandbox.
| Status | Test Case | Action |
|----------|--------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Success | Payment with Quote - responds with successful payment for BANKWIRE | 1. Send a Quote using 'transaction_reference' number starting with '09' and provide additional fields '701' with Recipient country and '7260' with 'BANKWIRE'. 2. Send a Payment using the same 'transaction_reference' and the proposal ID from the quote response. |
| Success | Payment (forward with fees included) - responds with successful payment for BANKWIRE | 1.Send Payment using 'transaction_reference' number starting with '09'. 2. Make sure to pass the paymentrequest.fx_type.forward object with fees-included =true in the request. 3. Provide Additional fields '701' with Recipient country and '7260' with 'BANKWIRE'. |
| Rejected | Payment with Quote - responds with rejected payment for BANKWIRE | 1. Send a Quote using 'transaction_reference' number starting with '04' and provide Additional fields '701' with Recipient country and '7260' with 'BANKWIRE'. 2. Send a Payment using the same 'transaction_reference' and the proposal ID from the quote response and recipient_account_uri's last 6 digits as '10####' (# is not literal but can be any number). |
| Rejected | Payment (forward with fees included) - responds with rejected payment for BANKWIRE | Send a Payment using 'transaction_reference' number starting with '04' and provide Additional fields '701' with Recipient country and '7260' with 'BANKWIRE' and recipient_account_uri's last 6 digits as '10####' (# is not literal but can be any number). |
## Sample Requests {#sample-requests}
### Payment Request Without Quote {#payment-request-without-quote}
* XML
* JSON
```XML
07-PYT-WQ-JHSDFR909202wfnvpkubv931455_4tel:+254108989tel:+254068989100.25USDUSARoyal ExchangeQuad CitiesNP021P2BSalJohnLDoeUSA123MainStreet#5AArlingtonVA22207USA1980-01-20WU123MainStreet#5AArlingtonVA22207CANcustomer@gmail.com1abdtr236
```
```JSON
{
"paymentrequest": {
"transaction_reference": "07-PYT-WQ-JHSDFR909202wfnvpkubv931455_4",
"sender_account_uri": "tel:+254108989",
"recipient_account_uri": "tel:+254068989",
"payment_amount": {
"amount": "100.25",
"currency": "USD"
},
"payment_origination_country": "USA",
"receiving_bank_name": "Royal Exchange",
"receiving_bank_branch_name": "Quad Cities",
"bank_code": "NP021",
"payment_type": "P2B",
"source_of_income": "Sal",
"sender": {
"first_name": "John",
"middle_name": "L",
"last_name": "Doe",
"nationality": "USA",
"address": {
"line1": "123MainStreet",
"line2": "#5A",
"city": "Arlington",
"country_subdivision": "VA",
"postal_code": "22207",
"country": "USA"
},
"date_of_birth": "1980-01-20"
},
"recipient": {
"organization_name": "WU",
"address": {
"line1": "123MainStreet",
"line2": "#5A",
"city": "Arlington",
"country_subdivision": "VA",
"postal_code": "22207",
"country": "CAN"
},
"email": "customer@gmail.com"
},
"payment_file_identifier": "1abdtr236"
}
}
```
### Payment (Without Quote) Request for BANKWIRE {#payment-without-quote-request-for-bankwire}
* XML
* JSON
```XML
07-PYT-WoQ-JHSDFR909202wfnvpkubv931455_4tel:+254108989ban:45678993;bic=UNBECNSHXXX100.25USDUSARoyal ExchangeQuad CitiesNP021P2BSalJohnLDoeUSA123MainStreet#5AArlingtonVA22207USA1980-01-20WU123MainStreet#5AArlingtonVA22207CHNcustomer@gmail.com701CHN7260BANKWIRE1abdtr236
```
```JSON
{
"paymentrequest": {
"transaction_reference": "07-PYT-WoQ-JHSDFR909202wfnvpkubv931455_4",
"sender_account_uri": "tel:+254108989",
"recipient_account_uri": "ban:45678993;bic=UNBECNSHXXX",
"payment_amount": {
"amount": "100.25",
"currency": "USD"
},
"payment_origination_country": "USA",
"receiving_bank_name": "Royal Exchange",
"receiving_bank_branch_name": "Quad Cities",
"bank_code": "NP021",
"payment_type": "P2B",
"source_of_income": "Sal",
"sender": {
"first_name": "John",
"middle_name": "L",
"last_name": "Doe",
"nationality": "USA",
"address": {
"line1": "123MainStreet",
"line2": "#5A",
"city": "Arlington",
"country_subdivision": "VA",
"postal_code": "22207",
"country": "USA"
},
"date_of_birth": "1980-01-20"
},
"recipient": {
"organization_name": "WU",
"address": {
"line1": "123MainStreet",
"line2": "#5A",
"city": "Arlington",
"country_subdivision": "VA",
"postal_code": "22207",
"country": "CHN"
},
"email": "customer@gmail.com"
},
"additional_data": {
"data_field": [
{
"name": "701",
"value": "CHN"
},
{
"name": "7260",
"value": "BANKWIRE"
}
]
},
"payment_file_identifier": "1abdtr236"
}
}
```
### Payment Request With Quote {#payment-request-with-quote}
#### Sender and Recipient Account URI not provided in payment {#sender-and-recipient-account-uri-not-provided-in-payment}
**Note**: Unlike the above shown "Payment without Quote" request, the payment and account information is not sent again in the request, but a proposal ID is provided instead.
Proposal ID is obtained from a previously submitted quote request.
* XML
* JSON
```XML
02-PYT-WQ-TGFSWECVBN-0094565645615222_6pen_40000994037586571936330328Royal ExchangeQuad CitiesSalJohnLDoeUSA123MainStreet5AArlingtonVA22207USAppn:123456789;expiration-date=2019-05-27;issue-date=2011-07-12;country=USA1985-06-24LeeMCardholderUSA123MainStreet5AArlingtonVA22207USAppn:541235632;expiration-date=2021-05-27;issue-date=2011-07-12;country=USA0016367224357customer@gmail.com
```
```JSON
{
"paymentrequest": {
"transaction_reference": "02-PYT-WQ-TGFSWECVBN-0094565645615222_6",
"proposal_id": "pen_40000994037586571936330328",
"receiving_bank_name": "Royal Exchange",
"receiving_bank_branch_name": "Quad Cities",
"source_of_income": "Sal",
"sender": {
"first_name": "John",
"middle_name": "L",
"last_name": "Doe",
"nationality": "USA",
"address": {
"line1": "123MainStreet",
"line2": "5A",
"city": "Arlington",
"country_subdivision": "VA",
"postal_code": "22207",
"country": "USA"
},
"government_ids": {
"government_id_uri": "ppn:123456789;expiration-date=2019-05-27;issue-date=2011-07-12;country=USA"
},
"date_of_birth": "1985-06-24"
},
"recipient": {
"first_name": "Lee",
"middle_name": "M",
"last_name": "Cardholder",
"nationality": "USA",
"address": {
"line1": "123MainStreet",
"line2": "5A",
"city": "Arlington",
"country_subdivision": "VA",
"postal_code": "22207",
"country": "USA"
},
"government_ids": {
"government_id_uri": "ppn:541235632;expiration-date=2021-05-27;issue-date=2011-07-12;country=USA"
},
"phone": "0016367224357",
"email": "customer@gmail.com"
}
}
}
```
### Payment Request With Quote {#payment-request-with-quote-1}
#### Sender and Recipient Account URI provided in payment {#sender-and-recipient-account-uri-provided-in-payment}
**Note**: Proposal ID does not contain Sender and Recipient URI so this is provided in payment request.
* XML
* JSON
```XML
0653d8effce785434a8f35323aees8siaftk05tc19lxy0afvtel:+54010894tel:+54010894JohnLDoeUSA123MainStreet#5AArlingtonNA12345USA1980-01-20JohnLDoeUSA123MainStreet#5AArlingtonNA12345CAN.
customer@gmail.comRegular IncomeRoyal ExchangeQuad Cities123456789
```
```JSON
{
"paymentrequest": {
"transaction_reference": "0653d8effce785434a8f353",
"proposal_id": "23aees8siaftk05tc19lxy0afv",
"sender_account_uri": "tel:+54010894",
"recipient_account_uri": "tel:+54010894",
"sender": {
"first_name": "John",
"middle_name": "L",
"last_name": "Doe",
"nationality": "USA",
"address": {
"line1": "123MainStreet",
"line2": "#5A",
"city": "Arlington",
"country_subdivision": "NA",
"postal_code": "12345",
"country": "USA"
},
"date_of_birth": "1980-01-20"
},
"recipient": {
"first_name": "DMS",
"middle_name": "M",
"last_name": "Abeysundera",
"nationality": "USA",
"address": {
"line1": "Nawam Mawatha",
"line2": "#5A",
"city": "Arlington",
"country_subdivision": "NA",
"postal_code": "12345",
"country": "CAN"
},
"email": "customer@gmail.com"
},
"receiving_bank_name": "Royal Exchange",
"receiving_bank_branch_name": "Quad Cities",
"payment_file_identifier": "123456789"
}
}
```
### Payment with Quote for BANKWIRE {#payment-with-quote-for-bankwire}
* XML
* JSON
```XML
02-PYT-WQ-TGFSWECVBN-0094565645615222_6pen_40000994037586571936330328Royal ExchangeQuad CitiesSalJohnLDoeUSA123MainStreet5AArlingtonVA22207USAppn:123456789;expiration-date=2019-05-27;issue-date=2011-07-12;country=USA1985-06-24LeeMCardholderUSA123MainStreet5AArlingtonVA22207USAppn:541235632;expiration-date=2021-05-27;issue-date=2011-07-12;country=USA0016367224357customer@gmail.com701USA7260BANKWIRE
```
```JSON
{
"paymentrequest": {
"transaction_reference": "02-PYT-WQ-TGFSWECVBN-0094565645615222_6",
"proposal_id": "pen_40000994037586571936330328",
"receiving_bank_name": "Royal Exchange",
"receiving_bank_branch_name": "Quad Cities",
"source_of_income": "Sal",
"sender": {
"first_name": "John",
"middle_name": "L",
"last_name": "Doe",
"nationality": "USA",
"address": {
"line1": "123MainStreet",
"line2": "5A",
"city": "Arlington",
"country_subdivision": "VA",
"postal_code": "22207",
"country": "USA"
},
"government_ids": {
"government_id_uri": "ppn:123456789;expiration-date=2019-05-27;issue-date=2011-07-12;country=USA"
},
"date_of_birth": "1985-06-24"
},
"recipient": {
"first_name": "Lee",
"middle_name": "M",
"last_name": "Cardholder",
"nationality": "USA",
"address": {
"line1": "123MainStreet",
"line2": "5A",
"city": "Arlington",
"country_subdivision": "VA",
"postal_code": "22207",
"country": "USA"
},
"government_ids": {
"government_id_uri": "ppn:541235632;expiration-date=2021-05-27;issue-date=2011-07-12;country=USA"
},
"phone": "0016367224357",
"email": "customer@gmail.com"
},
"additional_data": {
"data_field": [
{
"name": "701",
"value": "USA"
},
{
"name": "7260",
"value": "BANKWIRE"
}
]
}
}
}
```
### Payment with Carded Rate Request {#payment-with-carded-rate-request}
* XML
* JSON
```XML
09-PYT-WCR-HDFsWERTYLKR-883166274207676tel:+254108989ban:106050018728;bic=900117.15EURFRAP2PJohnLDoeUSA123MainStreet#5AArlingtonVA22207FRA1980-01-20DMSMAbeysunderaUSANawam Mawatha#5AArlingtonVA200LKAcustomer@gmail.comRoyal ExchangeQuad Cities1awedgt9false1200LKA-BK701LKA60072143whws68ojogpe16vc75sbx0lhn
```
```JSON
{
"paymentrequest": {
"transaction_reference": "09-PYT-WCR-HDFsWERTYLKR-883166274207676",
"sender_account_uri": "tel:+254108989",
"recipient_account_uri": "ban:106050018728;bic=900",
"payment_amount": {
"amount": "117.15",
"currency": "EUR"
},
"payment_origination_country": "FRA",
"payment_type": "P2P",
"sender": {
"first_name": "John",
"middle_name": "L",
"last_name": "Doe",
"nationality": "USA",
"address": {
"line1": "123MainStreet",
"line2": "#5A",
"city": "Arlington",
"country_subdivision": "VA",
"postal_code": "22207",
"country": "FRA"
},
"date_of_birth": "1980-01-20"
},
"recipient": {
"first_name": "DMS",
"middle_name": "M",
"last_name": "Abeysundera",
"nationality": "USA",
"address": {
"line1": "Nawam Mawatha",
"line2": "#5A",
"city": "Arlington",
"country_subdivision": "VA",
"postal_code": "200",
"country": "LKA"
},
"email": "customer@gmail.com"
},
"receiving_bank_name": "Royal Exchange",
"receiving_bank_branch_name": "Quad Cities",
"payment_file_identifier": "1awedgt9",
"fx_type": {
"forward": {
"fees_included": "false"
}
},
"additional_data": {
"data_field": [
{
"name": "1200",
"value": "LKA-BK"
},
{
"name": "701",
"value": "LKA"
},
{
"name": "600",
"value": "7214"
}
]
},
"card_rate_id": "3whws68ojogpe16vc75sbx0lhn"
}
}
```
### Payment with Carded Rate Request for BANKWIRE {#payment-with-carded-rate-request-for-bankwire}
* XML
* JSON
```XML
09-PYT-WCR-HDFsWERTYLKR-883166274207676tel:+254108989ban:106050018728;bic=900117.15USDUSAP2PJohnLDoeUSA123MainStreet#5AArlingtonVA22207USA1980-01-20DMSMAbeysunderaUSANawam Mawatha#5AArlingtonVA200CHNcustomer@gmail.comRoyal ExchangeQuad Cities1awedgt9false2601985-06-24701CHN7260BANKWIRE3whws68ojogpe16vc75sbx0lhn
```
```JSON
{
"paymentrequest": {
"transaction_reference": "09-PYT-WCR-HDFsWERTYLKR-883166274207676",
"sender_account_uri": "tel:+254108989",
"recipient_account_uri": "ban:106050018728;bic=900",
"payment_amount": {
"amount": "117.15",
"currency": "USD"
},
"payment_origination_country": "FRA",
"payment_type": "P2P",
"sender": {
"first_name": "John",
"middle_name": "L",
"last_name": "Doe",
"nationality": "USA",
"address": {
"line1": "123MainStreet",
"line2": "#5A",
"city": "Arlington",
"country_subdivision": "VA",
"postal_code": "22207",
"country": "USA"
},
"date_of_birth": "1980-01-20"
},
"recipient": {
"first_name": "DMS",
"middle_name": "M",
"last_name": "Abeysundera",
"nationality": "CHN",
"address": {
"line1": "Nawam Mawatha",
"line2": "#5A",
"city": "Arlington",
"country_subdivision": "VA",
"postal_code": "200",
"country": "CHN"
},
"email": "customer@gmail.com"
},
"receiving_bank_name": "Royal Exchange",
"receiving_bank_branch_name": "Quad Cities",
"payment_file_identifier": "1awedgt9",
"fx_type": {
"forward": {
"fees_included": "false"
}
},
"additional_data": {
"data_field": [
{
"name": "260",
"value": "1985-06-24"
},
{
"name": "701",
"value": "CHN"
},
{
"name": "7260",
"value": "BANKWIRE"
}
]
},
"card_rate_id": "3whws68ojogpe16vc75sbx0lhn"
}
}
```
## Sample Responses {#sample-responses}
The response fields would be same regardless if it's a payment with quote or payment with carded rate or payment without quote/ carded rate.
### Successful response: {#successful-response}
* XML
* JSON
```XML
02-PYT-SR-KSQTYUBNM-0094565645615222_76SUCCESSrem_zoALfF30XHku95_NCWQvAS24d1Mpen_40000994037586571936330328payment2019-09-09T04:46:19-05:002019-09-09T04:47:00-05:00USD5.35EUR10.25GBP82.63USD105.50tel:+25406005tel:+254069832USD121.10USAtrueGBPRoyal ExchangeQuad CitiesP2PSalGBP23.123.7833456828list3781012385145681318.22831CARDEDRATEID1225customer@gmail.com700USA7202W111123MainStreet 5A112Arlington114VA141USA11322207140USA101John102L103Doe1601985-06-24151PassportNumber1521234567891562019-05-271552011-07-12154USA211123MainStreet 5A212Arlington214VA241USA21322207201Lee202M203Cardholder2210016367224357251PassportNumber2521234567892562019-05-272552011-07-12254USA240USA
```
```JSON
{
"payment": {
"transaction_reference": "02-PYT-SR-KSQTYUBNM-0094565645615222_76",
"status": "SUCCESS",
"id": "rem_zoALfF30XHku95_NCWQvAS24d1M",
"proposal_id": "pen_40000994037586571936330328",
"resource_type": "payment",
"created": "2019-09-09T04:46:19-05:00",
"status_timestamp": "2019-09-09T04:47:00-05:00",
"fees_amount": {
"currency": "USD",
"amount": "5.35"
},
"charged_amount": {
"currency": "EUR",
"amount": "10.25"
},
"credited_amount": {
"currency": "GBP",
"amount": "82.63"
},
"principal_amount": {
"currency": "USD",
"amount": "105.50"
},
"sender_account_uri": "tel:+25406005",
"recipient_account_uri": "tel:+254069832",
"payment_amount": {
"currency": "USD",
"amount": "121.10"
},
"payment_origination_country": "USA",
"fx_type": {
"forward": {
"fees_included": "true",
"receiver_currency": "GBP"
}
},
"receiving_bank_name": "Royal Exchange",
"receiving_bank_branch_name": "Quad Cities",
"payment_type": "P2P",
"source_of_income": "Sal",
"settlement_details": {
"currency": "EUR",
"amount": "23.12"
},
"fx_rate": "3.7833456828",
"additional_data_list": {
"resource_type": "list",
"item_count": "37",
"data": {
"data_field": [
{
"name": "810",
"value": "123"
},
{
"name": "851",
"value": "456"
},
{
"name": "813",
"value": "18.22"
},
{
"name": "831",
"value": "CARDEDRATEID1"
},
{
"name": "225",
"value": "customer@gmail.com"
},
{
"name": "700",
"value": "USA"
},
{
"name": "7202",
"value": "W"
},
{
"name": "111",
"value": "123MainStreet 5A"
},
{
"name": "112",
"value": "Arlington"
},
{
"name": "114",
"value": "VA"
},
{
"name": "141",
"value": "USA"
},
{
"name": "113",
"value": "22207"
},
{
"name": "140",
"value": "USA"
},
{
"name": "101",
"value": "John"
},
{
"name": "102",
"value": "L"
},
{
"name": "103",
"value": "Doe"
},
{
"name": "160",
"value": "1985-06-24"
},
{
"name": "151",
"value": "PassportNumber"
},
{
"name": "152",
"value": "123456789"
},
{
"name": "156",
"value": "2019-05-27"
},
{
"name": "155",
"value": "2011-07-12"
},
{
"name": "154",
"value": "USA"
},
{
"name": "211",
"value": "123MainStreet 5A"
},
{
"name": "212",
"value": "Arlington"
},
{
"name": "214",
"value": "VA"
},
{
"name": "241",
"value": "USA"
},
{
"name": "213",
"value": "22207"
},
{
"name": "201",
"value": "Lee"
},
{
"name": "202",
"value": "M"
},
{
"name": "203",
"value": "Cardholder"
},
{
"name": "221",
"value": "0016367224357"
},
{
"name": "251",
"value": "PassportNumber"
},
{
"name": "252",
"value": "123456789"
},
{
"name": "256",
"value": "2019-05-27"
},
{
"name": "255",
"value": "2011-07-12"
},
{
"name": "254",
"value": "USA"
},
{
"name": "240",
"value": "USA"
}
]
}
}
}
}
```
### Successful Response for BANKWIRE: {#successful-response-for-bankwire}
* XML
* JSON
```XML
060e3dbc44-d3ff-44aa-b02a-9b4c2bff2977PENDINGrem_JQXJoVqkZ7RPTAaoL7CnimjzTPk2h52tavntgsvi3mo0gwfuat8yupayment2023-08-24T07:49:49-05:002023-08-24T07:49:53-05:00EligibleForSettlement2023-09-24T19:49:53.552-05:001.00USD8.35USD7.35USD8.35USDtel:+25406006iban:CH93007620116238529578.35USDUSAtrueUSDRoyal ExchangeQuad CitiesPOFICHBEXXXP2PRegular Income7.35USD1.000000list38131.000000840f7eiopk6aid4b1074puuv8b3xn841QUOTE_HONORED123456789
```
```JSON
{
"payment": {
"transaction_reference": "060e3dbc44-d3ff-44aa-b02a-9b4c2bff2977",
"status": "PENDING",
"id": "rem_JQXJoVqkZ7RPTAaoL7CnimjzTPk",
"proposal_id": "2h52tavntgsvi3mo0gwfuat8yu",
"resource_type": "payment",
"created": "2023-08-24T07:49:49-05:00",
"status_timestamp": "2023-08-24T07:49:53-05:00",
"pending_stage": "EligibleForSettlement",
"pending_max_completion_date": "2023-09-24T19:49:53.552-05:00",
"fees_amount": {
"amount": 1,
"currency": "USD"
},
"charged_amount": {
"amount": 8.35,
"currency": "USD"
},
"credited_amount": {
"amount": 7.35,
"currency": "USD"
},
"principal_amount": {
"amount": 8.35,
"currency": "USD"
},
"sender_account_uri": "tel:+25406006",
"recipient_account_uri": "iban:CH9300762011623852957",
"payment_amount": {
"amount": 8.35,
"currency": "USD"
},
"payment_origination_country": "USA",
"fx_type": {
"forward": {
"fees_included": true,
"receiver_currency": "USD"
}
},
"receiving_bank_name": "Royal Exchange",
"receiving_bank_branch_name": "Quad Cities",
"bank_code": "POFICHBEXXX",
"payment_type": "P2P",
"source_of_income": "Regular Income",
"settlement_details": {
"amount": 7.35,
"currency": "USD"
},
"fx_rate": 1,
"additional_data_list": {
"resource_type": "list",
"item_count": 3,
"data": {
"data_field": [
{
"name": 813,
"value": 1
},
{
"name": 840,
"value": "f7eiopk6aid4b1074puuv8b3xn"
},
{
"name": 841,
"value": "QUOTE_HONORED"
}
]
}
},
"payment_file_identifier": 123456789
}
}
```
### Rejected Response with Source: {#rejected-response-with-source}
* XML
* JSON
```XML
7622332Additional Data-1200-Destination Service TagMISSING_REQUIRED_INPUTMissing Required InputfalseErrorDetailCode092000
```
```JSON
{
"Errors": {
"Error": {
"RequestId": "7622332",
"Source": "Additional Data-1200-Destination Service Tag",
"ReasonCode": "MISSING_REQUIRED_INPUT",
"Description": "Missing Required Input",
"Recoverable": "false",
"Details": {
"Detail": {
"Name": "ErrorDetailCode",
"Value": "092000"
}
}
}
}
}
```
### Rejected Response without Source: {#rejected-response-without-source}
* XML
* JSON
```XML
7622332DECLINESending amount is greater than the maximum allowed per transactionfalseErrorDetailCode130118
```
```JSON
{
"Errors": {
"Error": {
"RequestId": "7622332",
"Source": "",
"ReasonCode": "DECLINE",
"Description": "Sending amount is greater than the maximum allowed per transaction",
"Recoverable": "false",
"Details": {
"Detail": {
"Name": "ErrorDetailCode",
"Value": "130118"
}
}
}
}
}
```
### Rejected Response for BANKWIRE: {#rejected-response-for-bankwire}
* XML
* JSON
```XML
117201280DECLINEInvalid recipient currencyfalseErrorDetailCode130101
```
```JSON
{
"Errors": {
"Error": {
"RequestId": 117201280,
"Source": "",
"ReasonCode": "DECLINE",
"Description": "Invalid recipient currency",
"Recoverable": false,
"Details": {
"Detail": {
"Name": "ErrorDetailCode",
"Value": 130101
}
}
}
}
}
```
### Validation Failure Response: {#validation-failure-response}
* XML
* JSON
```XML
170039recipient_account_uriMISSING_REQUIRED_INPUTMissing Required InputfalseErrorDetailCode092000170039sender.address.countryINVALID_INPUT_LENGTHInvalid lengthfalseErrorDetailCode072000
```
```JSON
{
"Errors": {
"Error": [
{
"RequestId": "170039",
"Source": "recipient_account_uri",
"ReasonCode": "MISSING_REQUIRED_INPUT",
"Description": "Missing Required Input",
"Recoverable": "false",
"Details": {
"Detail": {
"Name": "ErrorDetailCode",
"Value": "092000"
}
}
},
{
"RequestId": "170039",
"Source": "sender.address.country",
"ReasonCode": "INVALID_INPUT_LENGTH",
"Description": "Invalid length",
"Recoverable": "false",
"Details": {
"Detail": {
"Name": "ErrorDetailCode",
"Value": "072000"
}
}
}
]
}
}
```
### Pending Response: {#pending-response}
* XML
* JSON
```XML
05-PYT-PR-GAWERBNseYIOFUE-009675675_521PENDINGrem_AsJpZvQdkS9Rq779Bg93pmUOUqMpen_40000854024084319744151894payment2019-09-09T04:16:49-05:002019-09-09T04:17:30-05:00Processing2019-09-09T04:19:53.435-05:005.2510.25GBP82.63USD105.50tel:+25406005tel:+254069832USD121.10USAtrueGBPRoyal ExchangeQuad CitiesP2PSalEUR23.121234563.7833456828list3681012385145681318.22225customer@gmail.com700USA7202W111123MainStreet 5A112Arlington114VA141USA11322207140USA101John102L103Doe1601985-06-24151PassportNumber1521234567891562019-05-271552011-07-12154USA211123MainStreet 5A212Arlington214VA241USA21322207201Lee202M203Cardholder2210016367224357251PassportNumber2521234567892562019-05-272552011-07-12254USA240USA
```
```JSON
{
"payment": {
"transaction_reference": "05-PYT-PR-GAWERBNseYIOFUE-009675675_521",
"status": "PENDING",
"id": "rem_AsJpZvQdkS9Rq779Bg93pmUOUqM",
"proposal_id": "pen_40000854024084319744151894",
"resource_type": "payment",
"created": "2019-09-09T04:16:49-05:00",
"status_timestamp": "2019-09-09T04:17:30-05:00",
"pending_stage": "Processing",
"pending_max_completion_date": "2019-09-09T04:19:53-05:00",
"fees_amount": {
"currency": "",
"amount": "5.35"
},
"charged_amount": {
"currency": "",
"amount": "10.25"
},
"credited_amount": {
"currency": "GBP",
"amount": "82.63"
},
"principal_amount": {
"currency": "USD",
"amount": "105.50"
},
"sender_account_uri": "tel:+25406005",
"recipient_account_uri": "tel:+254069832",
"payment_amount": {
"currency": "USD",
"amount": "121.10"
},
"payment_origination_country": "USA",
"fx_type": {
"forward": {
"fees_included": "true",
"receiver_currency": "USD"
}
},
"receiving_bank_name": "Royal Exchange",
"receiving_bank_branch_name": "Quad Cities",
"payment_type": "P2P",
"source_of_income": "Sal",
"settlement_details": {
"currency": "EUR",
"amount": "23.12"
},
"cashout_code": "123456",
"fx_rate": "3.7833456828",
"additional_data_list": {
"resource_type": "list",
"item_count": "36",
"data": {
"data_field": [
{
"name": "810",
"value": "123"
},
{
"name": "851",
"value": "456"
},
{
"name": "813",
"value": "18.22"
},
{
"name": "225",
"value": "customer@gmail.com"
},
{
"name": "700",
"value": "USA"
},
{
"name": "7202",
"value": "W"
},
{
"name": "111",
"value": "123MainStreet 5A"
},
{
"name": "112",
"value": "Arlington"
},
{
"name": "114",
"value": "VA"
},
{
"name": "141",
"value": "USA"
},
{
"name": "113",
"value": "22207"
},
{
"name": "140",
"value": "USA"
},
{
"name": "101",
"value": "John"
},
{
"name": "102",
"value": "L"
},
{
"name": "103",
"value": "Doe"
},
{
"name": "160",
"value": "1985-06-24"
},
{
"name": "151",
"value": "PassportNumber"
},
{
"name": "152",
"value": "123456789"
},
{
"name": "156",
"value": "2019-05-27"
},
{
"name": "155",
"value": "2011-07-12"
},
{
"name": "154",
"value": "USA"
},
{
"name": "211",
"value": "123MainStreet 5A"
},
{
"name": "212",
"value": "Arlington"
},
{
"name": "214",
"value": "VA"
},
{
"name": "241",
"value": "USA"
},
{
"name": "213",
"value": "22207"
},
{
"name": "201",
"value": "Lee"
},
{
"name": "202",
"value": "M"
},
{
"name": "203",
"value": "Cardholder"
},
{
"name": "221",
"value": "0016367224357"
},
{
"name": "251",
"value": "PassportNumber"
},
{
"name": "252",
"value": "123456789"
},
{
"name": "256",
"value": "2019-05-27"
},
{
"name": "255",
"value": "2011-07-12"
},
{
"name": "254",
"value": "USA"
},
{
"name": "240",
"value": "USA"
}
]
}
}
}
}
```
## Pending Stages {#pending-stages}
Stages of a pending transaction:
| Pending Stage | Stage Description | Next Day Settlement Impact | Prefunding Settlement / Collateral Settlement Impact |
|---------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Processing | Transaction has been accepted and is being processed. This is the initial Pending stage. | None | Reserved Balance increases, and the Available Balance decreases. If there was a Quote Confirmed, then there is no change to the Reserved Balance or Available Balance, when the Payment is Pending Processing. |
| QueuedForFutureProcessing | Future Dated transaction has been accepted and queued in system till scheduled date provided in the Payment | None | There is no impact to Reserved or available balance |
| EligibleForSettlement | Transaction has been accepted, passed initial system validations, and has been passed to the receiving provider. | Transaction is in this stage at any time before the Processing cutoff, the Transaction Settlement Amount will be included in the Net Settlement Position. If later Rejected, a credit for the eligible portion of the Settlement Amount will becredited. | If the Transaction was previously in a Pending Processing stage, the Reserve Balance decreases. The Processing Amount increases, and the Available Balance remains unchanged. |
| Ambiguous | Transaction has initially been accepted but a processing anomaly occurred. The system will reattempt Transactions in this stage of Pending. Certain amount fields may be blank in the response in this stage, and subsequently update when a status changes. Transaction status updates can obtained using the Retrieve Payment API or the Status Change Report. | None | The customer may use the Balance API or the Operational Details in the Balance Management tool, to monitor the balances. |
| InsufficientBalance | Transaction has been accepted and is being queued. System will keep the transaction in queue for a fixed time duration(max queue time), shared in response of the Payment request. Enough balance needs to be added to settlement account prior to expiry of the queue time, to successfully process the payment. | None | Queued Balance increase. There is no impact to Reserved or Available Balance. |
| Any other value | Some Receiving Systems may return a response that does not align to the above statuses. In this instance, the Transaction will be in the Pending Stage of "Any Other Value". Customers should manage these miscellaneous indicators the same as a Transaction in the "Processing" stage and contact the support team if details on the exact meaning of the response are required. | None | The Customer may use the Balance API or the Operational Details in the Balance Management tool, to monitor the balances. |
## Error Codes {#error-codes}
Refer to complete list of error codes [here](https://developer.mastercard.com/cross-border-services/documentation/response-error-codes/index.md).
For information about the HTTP response codes that may be returned for your API requests, see [HTTP Response Codes](https://developer.mastercard.com/cross-border-services/documentation/response-error-codes/http-response-codes/index.md).