# Cash Pickup Locations API (Compliant with Payment Services Directive for EU customers)
source: https://developer.mastercard.com/cross-border-services/documentation/api-ref/psd2-eu-cash-pickup-apis/index.md

The Cash Pickup API is an optional service that allows customers to access a directory of eligible cash pickup locations visible to the sender. This API allows data filtering as per various parameters that include location types, country, city, and currency, offering customization for various program preferences and needs.   
Note: Customers must opt-in to access the Cash Pickup API.

The Cash Pickup API has three cash pickup location types:

* **Pickup Anywhere (PANY)** : This option allows cash pickup from any location of all available Receiving Service Providers (RSP) within the destination country. When the sender selects Pickup Anywhere option, the recipient has the flexibility to choose any convenient location for cash collection.  

* **Within Network** : This option allows the recipient to pick up cash from any location of a particular RSP within the destination country. When the Sender selects to deliver cash to an Within Network RSP, the recipient has the flexibility to choose any of the cash pickup locations within the selected RSP network boundaries.   

* **Directed**: This option provides a targeted solution for recipients who want to select a specific pickup location. Recipients collect their cash from one designated branch or retail site of a particular RSP in the destination country.

Alert:   

If you are a customer contracted with Mastercard Transaction Services (MTS) EU or UK, proceed to [Cash Pickup API Specification for EU](https://developer.mastercard.com/cross-border-services/documentation/api-ref/psd2-eu-cash-pickup-apis/index.md) and [Cash Pickup API Specification for UK](https://developer.mastercard.com/cross-border-services/documentation/api-ref/psd2-uk-cash-pickup-apis/index.md) respectively to ensure compliance with the relevant jurisdiction based on Regulatory Technical Standards (either EU or UK) derived from the Revised Payment Service Directive (PSD2).
Note: For **Cash Pickup Type** , include the request parameters as specified:  

* Pickup Anywhere : `PANY`
* Within Network : `IN_NETWORK`
* Directed: `DIRECT`

## Environment Domains {#environment-domains}

* Sandbox
* MTF
* Production

```Sandbox
https://sandbox.api.xbs.mastercard.eu/crossborder/cash-pickup
 
```

```MTF
https://mtf.api.xbs.mastercard.eu/crossborder/cash-pickup
 
```

```Production
https://api.xbs.mastercard.eu/crossborder/cash-pickup
```

## Catalog APIs {#catalog-apis}

### Countries {#countries}

* Provides information about a list of supported countries where cash pickup is available for recipients.
* This API is useful to retrieve the list of all cash pickup countries based on cash pickup type.


API Reference: `GET /countries?cash_pickup_type={cash_pickup_type}`

### Cities {#cities}

* Provides information about a list of supported cities where cash pickup service is available. This API is useful to retrieve the list from specific city locations supporting *Branches* type cash pickup.
* The `CityName` available in the response helps to filter the Receiving Service Providers and specific locations.
* The *Directed* cash pickup type is for recipients who prefer to pick up cash from a specific designated locations.


API Reference: `GET /cities?country={country}&currency={currency}&offset={offset}&limit={limit}`

### Receiving Service Providers {#receiving-service-providers}

* Provides information about the list of supported Receiving Service Providers offering cash pickup services.
* This API helps to identify a particular provider for the *Within Network Cash Pickup* type.
* You can use this API for *Within RSP Network* and *Branches* type.


API Reference: `GET /providers?country={country}&currency={currency}&cash_pickup_type={cash_pickup_type}&offset={offset}&limit={limit}`

### Branches {#branches}

* Provides information about locations specific to supported Receiving Service Providers that offer cash pickup services.
* The API helps to identify a particular location for *DirectCash Pickup Location* cash pickup type.
* Enter the `branchCode` you get in the response, in the `bankCode` field of the Payment API request.


API Reference: `GET /branches?provider_id={provider_id}&state={state}&city={city}&offset={offset}&limit={limit}`

For further information on URL and input parameter restrictions, refer to the [API Conventions](https://developer.mastercard.com/cross-border-services/documentation/api-basics/api-conventions/index.md) section.

* **Formats supported**: JSON
* **HTTP version**: 1.0/ 1.1
* **Required HTTP header parameters** :
  * `content-type` : Format of submitting the inbound content. Example: `application/json`
  * `content-length`: Length of the inbound content body in octets.
  * `partner-id`: String of alphanumeric special characters with a max length of 35. Example: `mts_4_006_interfaceid`.

Note: Mastercard recommends that you must update the catalog data once a week using the Catalog APIs.

## API Convention {#api-convention}

Refer to the [API Conventions](https://developer.mastercard.com/cross-border-services/documentation/api-basics/api-conventions/index.md) section for general guidelines.

## Payload Encryption {#payload-encryption}

Encrypt all the request payload before sending them to Mastercard. Similarly, you must decrypt the payload sent by Mastercard.   

For more detailed information, refer to the [Encryption and Decryption](https://developer.mastercard.com/cross-border-services/documentation/api-ref/encryption/index.md) section.

## 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.xbs.mastercard.eu/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.xbs.mastercard.eu/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.xbs.mastercard.eu/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.xbs.mastercard.eu/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}

#### ++Get countries based on the cash_pickup_type=PANY++ {#uget-countries-based-on-the-cash_pickup_typepanyu}

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-1}

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/response-error-codes/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/response-error-codes/http-response-codes/index.md) section.