# Quick Start Guide
source: https://developer.mastercard.com/cross-border-services/documentation/quick-start-guide/index.md

## Overview {#overview}

Use this guide to go from account setup to your first successful Sandbox request for Mastercard Cross-Border Services. You will create a project, generate credentials, make a test call, and prepare the same project for Production access.
Tip: If you want the fastest path to a working Sandbox request, use the [Insomnia Collection](https://developer.mastercard.com/cross-border-services/documentation/developer-tools/insomnia-collection/index.md). It is the recommended tool for first-time setup and testing on Sandbox, and it lets you test Sandbox and Production flows without writing code first.

### Before you begin {#before-you-begin}

* Create a [Mastercard Developers](https://developer.mastercard.com/) account.
* Have a secure place to store downloaded OAuth and encryption keys.
* Decide how you want to test: Insomnia, the reference application, or your own client.
* Know your authentication method: OAuth 1.0a is the default for most customers. If you are contracted with **MTS EU** or **MTS UK** , you must use OAuth 2.0 to comply with PSD2 requirements. See [API Basics](https://developer.mastercard.com/cross-border-services/documentation/api-basics/index.md) for more details.

### Sandbox checklist {#sandbox-checklist}

| # |      Step      |                                                                                                                                                                                     What to do                                                                                                                                                                                      |
|---|----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 1 | Access         | Get access to Mastercard Cross-Border Services and create your Mastercard Developers project.                                                                                                                                                                                                                                                                                       |
| 2 | Credentials    | Generate your Sandbox OAuth credentials and record your consumer key.                                                                                                                                                                                                                                                                                                               |
| 3 | Environment    | Confirm that you are using the Sandbox base URL and that your project is still in Sandbox mode.                                                                                                                                                                                                                                                                                     |
| 4 | Authentication | Configure OAuth signing. Configure OAuth 1.0a signing for the first request and confirm which consumer key and private key pair you will use. If you are contracted with **MTS EU** or **MTS UK** , use OAuth 2.0 instead. See [API Basics](https://developer.mastercard.com/cross-border-services/documentation/api-basics/index.md) for the OAuth 1.0a and OAuth 2.0 setup steps. |
| 5 | Encryption     | Complete payload encryption setup in [Transport Encryption](https://developer.mastercard.com/cross-border-services/documentation/api-basics/index.md#transport-encryption) section before testing any API flow. All Cross-Border Services payloads require encryption and responses require decryption.                                                                             |
| 6 | First call     | Send your first Sandbox request using the Sandbox base URL and preferred OAuth signing method.                                                                                                                                                                                                                                                                                      |
| 7 | Validation     | Use the sample response and [Testing](https://developer.mastercard.com/cross-border-services/documentation/testing/index.md) page to validate positive, negative, and follow-on flows.                                                                                                                                                                                              |

## Step 1: Get access to the API {#step-1-get-access-to-the-api}

1. Go to [Mastercard Developers](https://developer.mastercard.com/) and create an account.
2. Activate your account by opening the link sent to your email address, and log in.
3. Open your [My Projects](https://developer.mastercard.com/dashboard) page and start a new project. Sandbox access is open, so you can begin testing as soon as your project credentials are generated.

## Step 2: Create a project and generate Sandbox credentials {#step-2-create-a-project-and-generate-sandbox-credentials}

Create a Mastercard Developers project to generate your Sandbox credentials. Sandbox gives you simulated responses so you can validate your integration before requesting Production access.

### Project Details {#project-details}

1. Click **Create New Project** on your [My Projects](https://developer.mastercard.com/dashboard) page.

   ![project-details](https://static.developer.mastercard.com/content/cross-border-services/uploads/Step2_gettingStarted.PNG)
2. Enter a project name.

3. If prompted, indicate whether you are creating the project on behalf of a client.

4. In the **Select at least one API** field, choose **Mastercard Cross-Border Services**.

### Service Details {#service-details}

5. Complete the **Service details** form if it appears.

   Note: Some project flows include additional client or service fields. If you do not see them, continue to the next step.

### Project Credentials {#project-credentials}

6. In **Project Credentials** , select the **OAuth 1.0** radio button for this OAuth 1.0a service.

7. Enter your key alias and keystore password for your OAuth keys, record them securely, and click **Proceed**.

   ![create-oauth-key](https://static.developer.mastercard.com/content/cross-border-services/uploads/Step3_GettingStarted.PNG)

Warning: If you are a customer contracted with **MTS EU** or **MTS UK** , you must use OAuth 2.0 instead of OAuth 1.0a to comply with PSD2 regulations. Follow the [Getting Started with the APIs using OAuth 2.0](https://developer.mastercard.com/cross-border-services/documentation/api-basics/index.md#getting-started-with-the-apis-using-oauth-20) steps in API Basics (including mTLS setup) before proceeding.

### Additional Credentials {#additional-credentials}

8. Generate your encryption keys. All Cross-Border Services request payloads require encryption, so complete this step before testing any flow.

9. Enter your key alias and password for your encryption keys, record them securely, and click **Create Project**.

   ![create-encryption-key](https://static.developer.mastercard.com/content/cross-border-services/uploads/Step4_GettingStarted.PNG)
10. Download the OAuth 1.0a and encryption keys and store them in a safe place. Then click **Open Project**.

### Save the values you will need {#save-the-values-you-will-need}

11. On the project dashboard, record the following values:

* Sandbox and Production status

* Authentication consumer key

* Client encryption key fingerprint

  ![download-keys](https://static.developer.mastercard.com/content/cross-border-services/uploads/Step5_GettingStarted.PNG)

Note: Downloaded key files include your signing `.p12` (used for OAuth authentication) and your encryption `.p12` and `.pem` files (used to encrypt request payloads and decrypt response payloads). Store all files and their passwords securely; you will need them for every API call.

## Step 3: Confirm Sandbox configuration and make your first request {#step-3-confirm-sandbox-configuration-and-make-your-first-request}

Once you have Sandbox credentials, confirm the environment and configuration, then make a payment request to verify that your project is set up correctly.

### Sandbox environment and configuration {#sandbox-environment-and-configuration}

* Use the Sandbox base URL for all calls: `https://sandbox.api.mastercard.com/send`. If you are contracted with **MTS EU** or **MTS UK** , pass a `Host` header on every request: `sandbox.api.xbs.mastercard.eu` (EU) or `sandbox.api.xbs.mastercard.uk` (UK).
* Complete payload encryption setup before sending any request. All Cross-Border Services payloads must be encrypted. For the complete encryption configuration, see the [Transport Encryption](https://developer.mastercard.com/cross-border-services/documentation/api-basics/index.md#transport-encryption) section.

#### Before you run the request, make sure you have: {#before-you-run-the-request-make-sure-you-have}

* Your Sandbox consumer key
* Your OAuth signing setup:
  * **OAuth 1.0a:** your private key and a Mastercard OAuth library that generates `oauth_timestamp`, `oauth_nonce`, and `oauth_signature`
  * **OAuth 2.0 (MTS EU/UK):** your mTLS certificate and token flow configured. See [API Basics](https://developer.mastercard.com/cross-border-services/documentation/api-basics/index.md) for setup steps.
* Your encryption and decryption keys Note:   
  * Unlike some Mastercard APIs, Cross-Border Services requires payload encryption on every request, there is no unencrypted first-call shortcut.
  * For a complete client setup, see [API Basics](https://developer.mastercard.com/cross-border-services/documentation/api-basics/index.md).

For a full end-to-end walkthrough, use the tutorial that matches your authentication method:

* [API Tutorial using OAuth 1.0a](https://developer.mastercard.com/cross-border-services/documentation/tutorials/api-sdk-tutorial/index.md)
* [OAuth 2.0 Request Token tutorial](https://developer.mastercard.com/cross-border-services/documentation/tutorials/oauth2-api-sdk-tutorial-request-token/index.md) (for all APIs except Balance)
* [OAuth 2.0 Access Token tutorial](https://developer.mastercard.com/cross-border-services/documentation/tutorials/oauth2-api-sdk-tutorial-access-token/index.md) (for Balance API)

This first-call example uses `POST /send/v1/partners/{partner-id}/crossborder/payment` with the simplest payment flow (no prior quote required), so you can verify access, OAuth signing, payload encryption, and the Sandbox base URL before moving on to more complex flows.

```bash
curl --request POST \
  --url "https://sandbox.api.mastercard.com/send/v1/partners/YOUR_PARTNER_ID/crossborder/payment" \
  --header "Authorization: OAuth oauth_consumer_key=\"YOUR_CONSUMER_KEY\", oauth_signature_method=\"RSA-SHA256\", oauth_timestamp=\"1709596800\", oauth_nonce=\"a1b2c3d4e5f6\", oauth_version=\"1.0\", oauth_signature=\"YOUR_COMPUTED_SIGNATURE\"" \
  --header "Content-Type: application/json" \
  --data "ENCRYPTED_PAYLOAD"
```

Tip:   

* Refer to the [Testing](https://developer.mastercard.com/cross-border-services/documentation/testing/index.md) section for all Sandbox test cases.
* Refer to [API Basics](https://developer.mastercard.com/cross-border-services/documentation/api-basics/index.md#transport-encryption) for the full encryption setup.

```json
{
  "payment": {
    "transaction_reference": "QSG_SANDBOX_TEST_001",
    "id": "rem_AFO0lQZIOfo-DmbP4cZfoDzh_1",
    "resource_type": "payment",
    "created": "2026-08-13T10:30:00-05:00",
    "status": "PENDING",
    "status_timestamp": "2026-08-13T10:30:00-05:00",
    "pending_stage": "Processing",
    "fees_amount": {
      "amount": "3.50",
      "currency": "USD"
    },
    "charged_amount": {
      "amount": "103.50",
      "currency": "USD"
    },
    "credited_amount": {
      "amount": "82.40",
      "currency": "GBP"
    },
    "principal_amount": {
      "amount": "100.00",
      "currency": "USD"
    },
    "payment_amount": {
      "amount": "100.00",
      "currency": "USD"
    },
    "fx_rate": "0.8240",
    "payment_type": "P2P"
  }
}
```

### What success looks like {#what-success-looks-like}

* The request returns `200 OK`.
* The response body includes a transaction record with a stable `id` you can use for retrieval and follow-on flows.
* You can reuse the returned `id` values in the [Testing](https://developer.mastercard.com/cross-border-services/documentation/testing/index.md) page for retrieve, cancel, and other follow-on flows.

> **Test data:** The Sandbox returns simulated, static responses. For a negative-flow test, omit a required field or send an invalid value. The API returns `400 Bad Request` with a descriptive reason code. See [Testing](https://developer.mastercard.com/cross-border-services/documentation/testing/index.md) for additional Sandbox-specific scenarios.

## Step 4: Choose how you want to test and integrate {#step-4-choose-how-you-want-to-test-and-integrate}

After the first Sandbox request succeeds, pick the integration path that matches your workflow:

* **Insomnia:** Use the [Insomnia Collection](https://developer.mastercard.com/cross-border-services/documentation/developer-tools/insomnia-collection/index.md) page for setup.
* **Reference Application:** Use the [Reference Application](https://developer.mastercard.com/cross-border-services/documentation/developer-tools/ref-app/index.md) page.
* **Generated API client:** Follow the tutorial that matches your authentication method:
  * [API Tutorial using OAuth 1.0a](https://developer.mastercard.com/cross-border-services/documentation/tutorials/api-sdk-tutorial/index.md) (default for most customers)
  * [OAuth 2.0 Request Token tutorial](https://developer.mastercard.com/cross-border-services/documentation/tutorials/oauth2-api-sdk-tutorial-request-token/index.md) (MTS EU/UK, all APIs except Balance)
  * [OAuth 2.0 Access Token tutorial](https://developer.mastercard.com/cross-border-services/documentation/tutorials/oauth2-api-sdk-tutorial-access-token/index.md) (MTS EU/UK, Balance API only)
* **curl or a custom client:** Use the [Testing](https://developer.mastercard.com/cross-border-services/documentation/testing/index.md) page for test cases and additional request examples.

## Step 5: Validate your integration in the MTF environment {#step-5-validate-your-integration-in-the-mtf-environment}

Once your Sandbox integration is working, request access to the Mastercard Test Facility (MTF) environment to complete final validation before going live.

1. **Copy your Sandbox consumer key.** On your [My Projects](https://developer.mastercard.com/dashboard) page, open your project and copy the consumer key from the Sandbox keys section.
2. **Request MTF access.** Send an email to your assigned Mastercard implementation manager with your Sandbox consumer key to request access to the MTF environment.
3. **Complete MTF testing.** Your implementation manager creates a test plan and test cases for you to run in the MTF environment.

For full instructions, see the [MTF Access Guide](https://developer.mastercard.com/cross-border-services/documentation/tutorials/guide-mtf-access/index.md).

## Step 6: Promote the same project to Production {#step-6-promote-the-same-project-to-production}

Once your project is working in Sandbox, request Production access for that same project.

### Transition your project from Sandbox to Production {#transition-your-project-from-sandbox-to-production}

1. **Open your project in Mastercard Developers.** Go to your [My Projects](https://developer.mastercard.com/dashboard) page and open the Cross-Border Services project you used for Sandbox testing.

2. **Complete your profile.** This screen appears only if you have not completed your profile before.

   ![complete-profile](https://static.developer.mastercard.com/content/cross-border-services/uploads/Step2.1_SBS.PNG)
3. **Request Production access for that project.** In the project dashboard, click **Request Production Access** . Your Sandbox and Production statuses are shown separately on the project page, so you can track when Production moves from `Not Requested` to an enabled `Ready` state.

   ![request-production](https://static.developer.mastercard.com/content/cross-border-services/uploads/Step1_SBS_updated.png)
4. **Generate or download your Production keys.** After Production access is approved, download the Production OAuth and encryption keys for the same project. Keep the Production key material separate from your Sandbox keys.

   ![create-oauth-key](https://static.developer.mastercard.com/content/cross-border-services/uploads/Step3.PNG)
5. **Update your application configuration.** Switch the base URL from Sandbox to Production:

   * Sandbox: `https://sandbox.api.mastercard.com/send`
   * Production: `https://api.mastercard.com/send`

   Update your application to use the Production consumer key, signing key, and encryption certificates.

Note: Authentication and payload encryption work the same way in Sandbox and Production for both OAuth 1.0a and OAuth 2.0. The main changes are the Production key set, the Production approval state, and the Production base URL. For OAuth 2.0 (MTS EU/UK) customers, Production `Host` header values are provided during Production onboarding.

## Next Steps {#next-steps}

Continue with the documentation that matches your next task:

* [API Reference](https://developer.mastercard.com/cross-border-services/documentation/api-ref/index.md) for endpoint details
* [API Basics](https://developer.mastercard.com/cross-border-services/documentation/api-basics/index.md) for authentication, encryption, and client configuration
* [Testing](https://developer.mastercard.com/cross-border-services/documentation/testing/index.md) for additional request scenarios