# Cash Pickup API: Sandbox Testing
source: https://developer.mastercard.com/cross-border-services/documentation/testing/cashpickup-api/index.md

## Sandbox Testing {#sandbox-testing}

You can make API calls to the Sandbox environment from your application code using the [tutorials](https://developer.mastercard.com/cross-border-services/documentation/tutorials/index.md). This involves creating a project in Mastercard Developers, using the Sandbox keys to generate the required OAuth 1.0a Authorization Header.
Tip:   

* During the onboarding process, Mastercard assigns a registered partner ID to test in the higher environments (MTF and Production). Customers cannot access the Sandbox environment using this partner ID but can still access the Sandbox by using the non-registered partner ID.
* You can use any correctly formatted partner ID in the Sandbox.
* As a best practice, use the first 15 digits of your institution name (alphanumeric and/or special characters, no spaces) as the partner ID.
* For testing in the Sandbox environment, use the 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 completion of the Sandbox testing, Mastercard assigns a project manager for customers meeting the eligibility requirements for integrated testing in the MTF environment.
* The MTF environment has configuration to include requested receiving corridors, current foreign exchange rates, and fixed and variable fees specific to the customer.

## Sample Requests {#sample-requests}

### Common Request Headers {#common-request-headers}

* *Content-Type:* application/json;charset=UTF-8
* *Partner-Id:* mts_4_006_interfaceid

#### 1. Get countries based on cash pickup type {#1-get-countries-based-on-cash-pickup-type}

* Http

```http
https://sandbox.api.mastercard.com/crossborder/cash-pickup/countries?cash_pickup_type=PANY
```

* *HTTP Method:* GET
* *Endpoint:* `/crossborder/cash-pickup/countries`
* *Query Parameters:* `cash_pickup_type=PANY` Note: Here PANY is an example of cash pickup type.

#### 2. Get Cities based on the country and currency {#2-get-cities-based-on-the-country-and-currency}

* Http

```http
https://sandbox.api.mastercard.com/crossborder/cash-pickup/cities?country=GTM&currency=GTQ&offset=0&limit=2
```

* *HTTP Method:* GET
* *Endpoint:* `/crossborder/cash-pickup/cities`
* *Query Parameters:*
  * `country: GTM`
  * `currency: GTQ`
  * `offset: 0`
  * `limit: 2`

#### 3. Get Receiving Services Providers based on the country and currency {#3-get-receiving-services-providers-based-on-the-country-and-currency}

* Http

```http
https://sandbox.api.mastercard.com/crossborder/cash-pickup/providers?country=ARE&currency=AED&cash_pickup_type=IN_NETWORK&offset=0&limit=5
```

*HTTP Method:* GET

* *Endpoint:* `/crossborder/cash-pickup/providers`
* *Query Parameters:*
  * `country: ARE`
  * `currency: AED`
  * `cash_pickup_type: IN_NETWORK`
  * `offset: 0`
  * `limit: 5`

#### 4. Get Branches based on the provider ID {#4-get-branches-based-on-the-provider-id}

* Http

```http
https://sandbox.api.mastercard.com/crossborder/cash-pickup/branches?provider_id=ff1d9901-8e09-4840-b62b-464a22b1dd4e
```

* *HTTP Method:* GET
* *Endpoint:* `/crossborder/cash-pickup/branches`
* *Query Parameters:* `provider_id: ff1d9901-8e09-4840-b62b-464a22b1dd4e`

## Sample Responses {#sample-responses}

This section provides sample Cash Pickup API responses for different types of cash pickup locations.

### Cash Pickup Anywhere {#cash-pickup-anywhere}

#### 1. Get countries based on cash_pickup_type = PANY {#1-get-countries-based-on-cash_pickup_type--pany}

Customers submit `PANY` payments through Payment API and provide the destination country in VSF 701. No additional catalog details related to `PANY` are required in the payment request. Customers can use the Get Countries API to retrieve destination country and currency details while initiating the payment.

##### Successful Get Countries API Response {#successful-get-countries-api-response}

Note: Results are based on the cash pickup type. This example shows the result for `"cashPickupType": "PANY"`.
* JSON

```JSON
[
  {
    "items": [
      {
        "countryAlpha3": "QAT",
        "currency": "QAR",
        "cashPickupType": "PANY"
      },
      {
        "countryAlpha3": "BHR",
        "currency": "BHD",
        "cashPickupType": "PANY"
      },
      {
        "countryAlpha3": "GMB",
        "currency": "GMD",
        "cashPickupType": "PANY"
      },
      {
        "countryAlpha3": "ARE",
        "currency": "AED",
        "cashPickupType": "PANY"
      },
      {
        "countryAlpha3": "GIN",
        "currency": "GNF",
        "cashPickupType": "PANY"
      },
      {
        "countryAlpha3": "BFA",
        "currency": "XOF",
        "cashPickupType": "PANY"
      }
    ]
  }
]

```

### Within RSP Network {#within-rsp-network}

Customers submit `IN_NETWORK` payments through Payment API network and provide:

* Destination country in VSF 701
* Provider code in the bank code field

To retrieve the provider code, customers must call the following APIs in sequence:

#### 1. Get Countries API {#1-get-countries-api}

##### Successful Get Countries API Response {#successful-get-countries-api-response-1}

* JSON

```JSON
[
  {
    "items": [
      {
        "countryAlpha3": "QAT",
        "currency": "QAR",
        "cashPickupType": "IN_NETWORK"
      },
      {
        "countryAlpha3": "IND",
        "currency": "INR",
        "cashPickupType": "IN_NETWORK"
      },
      {
        "countryAlpha3": "BHR",
        "currency": "BHD",
        "cashPickupType": "IN_NETWORK"
      },
      {
        "countryAlpha3": "VNM",
        "currency": "USD",
        "cashPickupType": "IN_NETWORK"
      }
    ]
  }
]

```

#### 2. Get Providers API {#2-get-providers-api}

##### Successful Get Providers API Response {#successful-get-providers-api-response}

* JSON

```JSON
{
  "count": 3,
  "offset": 0,
  "limit": 50,
  "total": 3,
  "items": [
    {
      "providerId": "6532b90f-166d-41da-95ed-a24045c80f3e",
      "providerCode": "JA04",
      "providerName": "JMMB MONEY TRANSFER LIMITED",
      "country": "JAM",
      "currency": "JMD",
      "cashPickupType": "IN_NETWORK"
    },
    {
      "providerId": "90becc19-4b5e-456d-ade0-371300dc4bef",
      "providerCode": "JA05",
      "providerName": "JN MONEY",
      "country": "JAM",
      "currency": "JMD",
      "cashPickupType": "IN_NETWORK"
    },
    {
      "providerId": "7a05c930-a8fd-424c-a2a8-c376b9db6457",
      "providerCode": "JM02",
      "providerName": "VMBS MONEY TRANSFER SERVICES LTD",
      "country": "JAM",
      "currency": "JMD",
      "cashPickupType": "IN_NETWORK"
    }
  ]
}
```

### Branches {#branches}

Customers submit DIRECT payments through the Payment API and provide:

* Destination country in VSF 701
* Branch code in the bank code field

To retrieve branch code details, customers must call the following APIs in sequence:

#### 1. Get Countries API. {#1-get-countries-api-1}

##### Successful Get Countries API Response {#successful-get-countries-api-response-2}

* JSON

```JSON
[
  {
    "items": [
      {
        "countryAlpha3": "NGA",
        "currency": "NGN",
        "cashPickupType": "DIRECT"
      },
      {
        "countryAlpha3": "IND",
        "currency": "INR",
        "cashPickupType": "DIRECT"
      },
      {
        "countryAlpha3": "HND",
        "currency": "HNL",
        "cashPickupType": "DIRECT"
      },
      {
        "countryAlpha3": "IDN",
        "currency": "USD",
        "cashPickupType": "DIRECT"
      },
      {
        "countryAlpha3": "IDN",
        "currency": "IDR",
        "cashPickupType": "DIRECT"
      }
    ]
  }
]
```

#### 2. Get Cities API. {#2-get-cities-api}

To retrieve state and city details, customers must pass the Country and Currency in the Get Cities API.

##### Successful Cities API Response {#successful-cities-api-response}

* JSON

```JSON
{
  "count": 5,
  "offset": 1,
  "limit": 5,
  "total": 20,
  "items": [
    {
      "country": "PER",
      "currency": "PEN",
      "city": "LA OROYA",
      "stateName": "PERU"
    },
    {
      "country": "PER",
      "currency": "PEN",
      "city": "SURQUILLO",
      "stateName": "PERU"
    },
    {
      "country": "PER",
      "currency": "PEN",
      "city": "JAEN",
      "stateName": "PERU"
    },
    {
      "country": "PER",
      "currency": "PEN",
      "city": "MAIRANA",
      "stateName": "BOLIVIA"
    },
    {
      "country": "PER",
      "currency": "PEN",
      "city": "CHORRILLOS",
      "stateName": "PERU"
    }
  ]
}

```

#### 3. Get Providers {#3-get-providers}

Helps to retrieve RSPs based on country, currency, cash pickup type, and city.

##### Successful Receiving Service Providers API Response {#successful-receiving-service-providers-api-response}

* JSON

```JSON
{
  "count": 1,
  "offset": 0,
  "limit": 50,
  "total": 1,
  "items": [
    {
      "providerId": "cf64ecdf-2823-44bb-9067-f7aeaca56c70",
      "providerCode": "PE29",
      "providerName": "BANCO DE CREDITO PERU - TN",
      "country": "PER",
      "currency": "PEN",
      "cashPickupType": "DIRECT"
    }
  ]
}

```

#### 4. Get Branches {#4-get-branches}

Helps to retrieve branch-level details by passing the Provider ID from Get Providers API.

##### Successful Specific Location API Response {#successful-specific-location-api-response}

* JSON

```JSON
{
  "count": 2,
  "offset": 0,
  "limit": 50,
  "total": 2,
  "items": [
    {
      "providerId": "78dabafc-c1a5-4fd8-959d-37334fc41a67",
      "providerCode": "PE24",
      "providerName": "JET PERU S.A.",
      "country": "PER",
      "currency": "USD",
      "cashPickupType": "DIRECT",
      "branchId": "6831b131-bb35-4e1d-ab14-faaf5892a7e1",
      "branchCode": "PE240314",
      "branchCity": "INDEPENDENCIA",
      "branchState": "PERU",
      "branchAddress": "AV. ALFREDO MENDIOLA NO.3900 LOC. 1160 SUPERMERCADO METRO"
    },
    {
      "providerId": "78dabafc-c1a5-4fd8-959d-37334fc41a67",
      "providerCode": "PE24",
      "providerName": "JET PERU S.A.",
      "country": "PER",
      "currency": "USD",
      "cashPickupType": "DIRECT",
      "branchId": "275bc15a-a9f7-4b98-b728-3a4986bc5b13",
      "branchCode": "PE240292",
      "branchCity": "INDEPENDENCIA",
      "branchState": "PERU",
      "branchAddress": "AV. GERARDO UNGER 6911 LOCAL LB-82 C.C. PLAZA NORTE TERMINAL TERRESTRE"
    }
  ]
}

```

### Sample Retrieve Failures {#sample-retrieve-failures}

This section provides examples of error responses returned by Retrieve APIs.

#### Rejected Response With Error Codes {#rejected-response-with-error-codes}

##### 1.Invalid Input Value {#1invalid-input-value}

###### Error Response {#error-response}

* JSON

```JSON
{
  "Errors": {
    "Error": [
      {
        "RequestId": "2ra9lyarftumf01dpjnmo6jnw5",
        "Source": "cash_pickup_type",
        "ReasonCode": "MISSING_REQUIRED_INPUT",
        "Description": "Missing Required Input",
        "Recoverable": false,
        "Details": {
          "Detail": [
            {
              "name": "ErrorDetailCode",
              "value": "092000"
            }
          ]
        }
      }
    ]
  }
}

```

##### 2.Unauthorized Access {#2unauthorized-access}

###### Error Response {#error-response-1}

* JSON

```JSON
{
  "Errors": {
    "Error": [
      {
        "Source": "SYSTEM",
        "RequestId": "0.bf58d617.1729858126.38c9719",
        "ReasonCode": "AUTHORIZATION_FAILED",
        "Description": "Unauthorized Access",
        "Recoverable": "false",
        "Details": {
          "Detail": {
            "Name": "ErrorDetailCode",
            "Value": "050007"
          }
        }
      }
    ]
  }
}

```

### Sample Payment Request {#sample-payment-request}

A few samples of successful payment request as per the request parameters are:

#### PANY {#pany}

##### Sample Payment With Proposal ID {#sample-payment-with-proposal-id}

* XML

```XML
<paymentrequest>
  <transaction_reference>0653d8effce785434a8f353</transaction_reference>
  <proposal_id>23aees8siaftk05tc19lxy0afv</proposal_id>
  <sender_account_uri>tel:+54010894</sender_account_uri>
  <recipient_account_uri>ewallet:abcdefgh.fghh;sp=transpay</recipient_account_uri>
  <sender>
    <first_name>John</first_name>
    <middle_name>L</middle_name>
    <last_name>Doe</last_name>
    <nationality>USA</nationality>
    <address>
      <line1>123MainStreet</line1>
      <line2>#5A</line2>
      <city>Arlington</city>
      <country_subdivision>NA</country_subdivision>
      <postal_code>12345</postal_code>
      <country>USA</country>
    </address>
    <date_of_birth>1980-01-20</date_of_birth>
  </sender>
  <recipient>
    <first_name>John</first_name>
    <middle_name>L</middle_name>
    <last_name>Doe</last_name>
    <nationality>USA</nationality>
    <address>
      <line1>123MainStreet</line1>
      <line2>#5A</line2>
      <city>Arlington</city>
      <country_subdivision>NA</country_subdivision>
      <postal_code>12345</postal_code>
      <country>CAN</country>.</address>
    <email>customer@gmail.com</email>
  </recipient>
  <source_of_income>Regular Income</source_of_income>
  <receiving_bank_name>Royal Exchange</receiving_bank_name>
  <receiving_bank_branch_name>Quad Cities</receiving_bank_branch_name>
  <payment_file_identifier>123456789</payment_file_identifier>
  <fx_type>
    <forward>
      <sender_currency>USD</sender_currency>
    </forward>
  </fx_type>
  <payment_type>P2P</payment_type>
  <additional_data>
    <data_field>
      <name>7260</name>
      <value>CASH</value>
    </data_field>
    <data_field>
      <name>701</name>
      <value>ISR</value>
    </data_field>
  </additional_data>
</paymentrequest>
```

#### IN NETWORK {#in-network}

##### Sample Payment With Carded Rate ID {#sample-payment-with-carded-rate-id}

* XML

```XML
<paymentrequest>
  <transaction_reference>{% uuid 'v4' %}</transaction_reference>
  <sender_account_uri>tel:+254167419</sender_account_uri>
  <recipient_account_uri>ewallet:abcdefgh.fghh;sp=transpay</recipient_account_uri>
  <payment_amount>
    <amount>100.12</amount>
    <currency>USD</currency>
  </payment_amount>
  <payment_origination_country>USA</payment_origination_country>
  <bank_code>JM04</bank_code>
  <payment_type>P2P</payment_type>
  <card_rate_id>1001z7atjei9t01ilf78s32vuy5</card_rate_id>
  <sender>
    <first_name>John</first_name> <middle_name>L</middle_name>  <last_name>Doe</last_name>
    <nationality>USA</nationality>
    <address>
      <line1>123MainStreet</line1>  <line2>#5A</line2>   <city>Arlington</city>
      <country_subdivision>NA</country_subdivision>
      <postal_code>12345</postal_code>
      <country>USA</country>
    </address>
    <date_of_birth>1980-01-20</date_of_birth>
  </sender>
  <recipient>
    <first_name>John</first_name>  <middle_name>L</middle_name>  <last_name>Doe</last_name>
    <nationality>JAM</nationality>
    <address>
      <line1>123MainStreet</line1>  <line2>#5A</line2>  <city>Arlington</city>
      <country_subdivision>NA</country_subdivision>
      <postal_code>12345</postal_code>
      <country>JAM</country>
    </address>
    <email>customer@gmail.com</email>
  </recipient>
  <source_of_income>Regular Income</source_of_income>
  <receiving_bank_name>Royal Exchange</receiving_bank_name>
  <receiving_bank_branch_name>Quad Cities</receiving_bank_branch_name>
  <payment_file_identifier>123456789</payment_file_identifier>
  <receiver_currency>JMD</receiver_currency>
  <additional_data>
    <data_field>
      <name>7260</name>
      <value>CASH</value>
    </data_field>

    <data_field>
      <name>701</name>
      <value>JAM</value>
    </data_field>
  </additional_data>
</paymentrequest>
```

#### DIRECT {#direct}

##### Sample Payment With One Shot {#sample-payment-with-one-shot}

* XML

```XML
<paymentrequest>
  <transaction_reference>{% uuid 'v4' %}</transaction_reference>
  <sender_account_uri>tel:+254167419</sender_account_uri>
  <recipient_account_uri>ewallet:abcdefgh.fghh;sp=transpay</recipient_account_uri>
  <payment_amount>
    <amount>50.00</amount>
    <currency>USD</currency>
  </payment_amount>
  <payment_origination_country>USA</payment_origination_country>
  <bank_code>PE240294</bank_code>
  <payment_type>P2P</payment_type>
  <sender>
    <first_name>Jerry</first_name>
    <middle_name>L</middle_name>
    <last_name>Doe</last_name>
    <nationality>USA</nationality>
    <address>
      <line1>123MainStreet</line1>
      <line2>#5A</line2>
      <city>Arlington</city>
      <country_subdivision>NA</country_subdivision>
      <postal_code>12345</postal_code>
      <country>USA</country>
    </address>
    <date_of_birth>1980-01-20</date_of_birth>
    <government_ids>
      <government_id_uri>ppn:123456789;expiration-date=2024-05-27;issue-date=2011-07-12;country=USA</government_id_uri>
    </government_ids>
  </sender>
  <recipient>
    <first_name>ABC</first_name>
    <middle_name>L</middle_name>
    <last_name>Doe</last_name>
    <nationality>USA</nationality>
    <address>
      <line1>PERU</line1>
      <line2>Canton Vi Pila</line2>
      <city>HUARAL</city>
      <country_subdivision>PER</country_subdivision>
      <postal_code>41002</postal_code>
      <country>PER</country>
    </address>
    <email>customer@gmail.com</email>
  </recipient>
  <fx_type>
    <forward>
      <fees_included>true</fees_included>
      <receiver_currency>PEN</receiver_currency>
    </forward>
  </fx_type>
  <additional_data>

    <data_field>
      <name>701</name>
      <value>PER</value>
    </data_field>

    <data_field>
      <name>7260</name>
      <value>CASH</value>
    </data_field>

  </additional_data>
</paymentrequest>
```

## Error Codes {#error-codes}

Refer to the complete list of error codes [here](https://developer.mastercard.com/cross-border-services/documentation/code-and-formats/index.md).

For information about the HTTP response codes applicable to your API requests, refer to the [HTTP response codes](https://developer.mastercard.com/cross-border-services/documentation/code-and-formats/index.md) section.