# Quick Start Guide source: https://developer.mastercard.com/payment-initiation-api/documentation/quick-start-guide/index.md ## Overview {#overview} The Payment Initiation API allows businesses to initiate commercial card payments using the ISO 20022 standard. It enables secure, automated card payment processing for commercial transactions. This guide outlines the steps required to complete account setup, create a project, generate credentials, submit a Sandbox test request for Payment Initiation API, and prepare the project for Production access. ### 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. * Select the testing option to use: Postman, Insomnia, the reference application, or your own client. ### Sandbox checklist {#sandbox-checklist} | # | Step | What to do | |---|-------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 1 | Access | Get access to Payment Initiation API and create your Mastercard Developers project. | | 2 | Credentials | Generate your Sandbox OAuth credentials and record your consumer key. | | 3 | Encryption | If testing the API requests or other protected‑payload flows, complete the field‑level encryption configuration as described in API Basics before proceeding. | | 4 | First call | Send your first Sandbox request using the Sandbox base URL and OAuth 1.0a signing. | | 5 | Validation | Use the sample response and [Testing](https://developer.mastercard.com/payment-initiation-api/documentation/testing/index.md) page to validate test data, positive flows, and negative flows. | | 5 | Production | After Sandbox validation is complete, use Step 5 and the [Onboarding Checklist](https://developer.mastercard.com/payment-initiation-api/documentation/tutorial-and-guide/onboarding-checklist/index.md) to request Production access. | ## Step 1: Get access to the API {#step-1-get-access-to-the-api} 1. Navigate to [Mastercard Developers](https://developer.mastercard.com/) and select **Sign up** to create an account. 2. Activate the account by opening the link sent to the registered email address, then sign in. 3. Request access to the API if required. APIs marked with a lock icon require permission to view documentation and create a project. Access is granted by submitting an access request form. After submission, an email confirmation is sent indicating whether access has been approved or denied. ## Step 2: Create a project and generate Sandbox credentials {#step-2-create-a-project-and-generate-sandbox-credentials} To generate Sandbox and Production credentials, create a new Mastercard Developers project. Sandbox credentials provide access to a test environment with rich mocked data for learning and validation. 1. Navigate to the [My Projects](https://developer.mastercard.com/dashboard) page and select **Create new project**. 2. Enter a project name. 3. Verify that "Are you creating this project on behalf of a client?" is set to **No** (this option is selected by default). 4. Select **Payment Initiation** in the **Select your API service** drop-down list, then select **Proceed** . ![Screenshot of the Mastercard Developers ‘Project details’ page showing fields to enter a project name, indicate whether the project is created on behalf of a client, select the API service, and choose the commercial countries for the project.](https://static.developer.mastercard.com/content/payment-initiation-api/uploads/create-new-project.png) 5. Provide the service details by filling out the form and select **Proceed** . ![Screenshot of the Service Details page in Mastercard Developers showing required fields for configuring the Payment Initiation service, including business details, address, organization identifier, customer identifiers, and options for initiating payment instruction.](https://static.developer.mastercard.com/content/payment-initiation-api/uploads/service-details-sandbox.png) | Field | Description | Example value | Required? | |------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------|-----------| | Legal Business Name | Identifies the legal business name of the Buyer receiving the payment. | payment-initiation-demo | Yes | | Legal Address Line 1 | Business address line 1 | 2200 Mastercard Blvd | Yes | | Legal Address Line 2 | Business address line 2 | AddressLine2 | No | | Legal Address Line 3 | Business address line 3 | 2200 Mastercard Blvd | No | | Town Name | Identifies the name of the city or geographical location of the address. | New York | Yes | | Country Subdivision/State | Identifies the subdivision within a country where the business is located, such as the state, region, or county. | Vatican City | Yes | | Postcode | Identifies the mailing or ZIP code for the business. | 22043 | Yes | | Country | Identifies the country where the business is located. | United States of America | Yes | | Organization Identifier Type | Organization or identification type. | TXID | Yes | | Organization Identifier | Organization or tax identification number. | 123456789 | Yes | | Customer Identifier (CID) | A master identification number for all Mastercard customers. It can be 6-11 digits in length, but all CIDs issued today are 6 digits in length. A CID identifies a customer's unique legal entity. If a customer is defined by their legal entity, each customer should have one CID. If a customer has multiple legal entities, they can have multiple CIDs, with one for each entity. There is no limit to the number of legal entities that a customer can have. CIDs for unique legal entities under one customer can be tied together with a legal grandparent number. Currently some customers have multiple CIDs for one legal entity. | 123456 | Yes | | Customer ICA | Interbank Card Association. Used for agent identification in all service requests for core operations. | 123456 | Yes | | Will you be initiating the API requests to make payments on behalf of a Buyer? | The answer to this question helps identify if you are a direct or indirect Commercial Direct Payments customer. **Note: If you are unsure what type of user you are, refer to the tip below.** | Yes | Yes | | Will you be initiating the API requests to make payments on behalf of a Payment Agent? If yes, click the appropriate role from the list below. | A customer service provider is defined as a person (entity) that performs Program Service that is an agent of the Customer that receives or otherwise benefits from Program Service, whether directly or indirectly, performed by such Service Provider. A Mastercard Vendor is defined as a person (entity) that provides services to Mastercard. If you are not transacting on behalf of a Buyer, you must select either Customer Service Provider or Mastercard Vendor. **Note: If you are unsure what type of user you are, refer to the tip below.** | N/A | Yes | | Notification URL | A unique resource location for Commercial Direct Payments service to send event notifications. | `https://demonotificationurl.com` | Yes | Tip: Prospective users should review the agent types outlined in the table below. | Agent type | Initiate payments? | Customer type | |------------------------------------------|--------------------|---------------------------| | Debtor Agent | Yes | N/A | | Mastercard Service Provider | No | Mastercard Vendor | | Processor | No | Customer Service Provider | | Debtor Agent Processor | Yes | Customer Service Provider | | Debtor Agent Mastercard Service Provider | Yes | Mastercard Vendor | 6. Create and securely store a key alias and keystore password for the OAuth 1.0a project keys, then select **Proceed** . ![Screenshot of the Project Credentials step in Mastercard Developers showing fields to generate OAuth 1.0a project keys, including key alias and keystore password, with an option to skip the step or create keys using a CSR file.](https://static.developer.mastercard.com/content/payment-initiation-api/uploads/project-credentials-sandbox.png) 7. Create and record a key alias and keystore password for the encryption keys, then select **Create Project** . ![Create New Project screen showing the ‘Additional credentials’ step. The Payment Initiation service is selected, with sections for Client Encryption Key information and Mastercard Encryption Key inputs, including fields for key alias and keystore password. Navigation buttons include Skip this step, Back, and Create Project.](https://static.developer.mastercard.com/content/payment-initiation-api/uploads/additional-credentials-sandbox.png) 8. Select **Download key file** and securely store the OAuth and encryption keys, then select **Open Project** . ![Screenshot of the ‘Creating your project’ page in Mastercard Developers showing progress indicators for generating keys, creating the project, and preparing keys. A message reminds the user to download their key file, with a button to download the key and another to open the project.](https://static.developer.mastercard.com/content/payment-initiation-api/uploads/project-completion-sandbox.png) 9. Select **Get started** to complete the Production access prerequisites. ![Project Summary page with Payment Initiation API ready in sandbox, production access not requested, and links to documentation and support.](https://static.developer.mastercard.com/content/payment-initiation-api/uploads/summary.png) 10. Select the commercial countries for the project in the **Select your commercial countries** drop-down list and select **Submit** . This field indicates the client's operating countries. ![Modal dialog titled “Provide commercial countries” displayed on the Project page, with a searchable country selection field and Cancel and Submit buttons.](https://static.developer.mastercard.com/content/payment-initiation-api/uploads/commercial-countries.png) Note: If you are creating a project on behalf of a client, the field `Commercial countries` represent where your client is doing business. 11. From the Project page take note of your: 1. Sandbox and Production status ('Ready/Not Requested') ![Screenshot of the Mastercard Developers project summary page showing the sandbox client ID, the list of project APIs with Payment Initiation marked as ready in Sandbox, and options to add a new API or delete the project.](https://static.developer.mastercard.com/content/payment-initiation-api/uploads/summary-overview.png) 2. Sandbox and Production credentials: authentication consumer key and client encryption key fingerprint. ![Sandbox credentials page showing OAuth keys and API keys for a payment initiation project.](https://static.developer.mastercard.com/content/payment-initiation-api/uploads/credentials.png) Warning: **Key Expiry:** Mastercard Payment Initiation API Sandbox and Production Keys will expire after one year. You will have to generate a new set of keys after they expire. ## Step 3: Make your first Sandbox request {#step-3-make-your-first-sandbox-request} Once you have Sandbox credentials, make a simple GET request to confirm that your project is set up correctly. Before you run the request, make sure you have: * Your Sandbox consumer key * The private key used to sign OAuth requests * A Mastercard OAuth library or signer that generates `oauth_timestamp`, `oauth_nonce`, and `oauth_signature` This first-call example uses `GET /Retrieve a Debtor Registration`, so you can verify access, OAuth signing, and the Sandbox base URL before moving on to encrypted flows. Note: For a full client setup, including encryption configuration, see the [API Basics](https://developer.mastercard.com/payment-initiation-api/documentation/api-basics/index.md) section. **Example Request (cURL):** ```bash curl --request GET \ --url https://sandbox.api.mastercard.com/commercial/payments/debtor-agents/844555779/debtors \ --header 'Authorization: OAuth oauth_body_hash="47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=",oauth_consumer_key="6EHp1SL21WnR3t-EIyI9PzsKK56-b0qsWdDorN9z5e9d79eb!6277d5131ef844a7a035d57f745c1cd60000000000000000",oauth_nonce="UEsxgDPQ",oauth_signature_method="RSA-SHA256",oauth_timestamp="1776268065",oauth_version="1.0",oauth_signature="RYaqjMhxyh4PgSWiR5QAxJdrxo6H0CSwDcUO7M9%2FYyi8%2BtYCorsHTBcjZLxBgTLGpV8XzGRLSZDK9Z%2B5C2BDrmZRCFDhMcZhvk%2FdlpcjI4hAWx4%2FY6BRRlEXSd4LQR2sJDHBep8ehUf7YA7IShJuhjXDQAKjVYX4Mf%2FeIegoznStUnglYbj7oQkrF1TKWOBgt4%2BsdASuDCW5qaONV3SaDi7bAfvNyT06UyKgl9O7VRGByHjn%2ByOuogAlAsMB6h3yUTosxqy6zaLyjwB7QteacH5CU8Rhdo7wn0iIfUHKvNI0VhWxO3z8cEVEqsheYILDz2xElehiFrXBHtjQy2HbqA%3D%3D"' \ ``` > This example shows the required OAuth 1.0a header fields explicitly, but uses placeholders for sensitive values. Replace `YOUR_CONSUMER_KEY` with the consumer key from your project and generate `oauth_signature` with a Mastercard OAuth library. The library also handles `oauth_timestamp` and `oauth_nonce` for you. **Expected Response:** ```json { "data": { "count": 0, "items": [], "limit": 25, "offset": 0, "total": 0 } } ``` ## Step 4: Choose how you want to test and integrate {#step-4-choose-how-you-want-to-test-and-integrate} ### Generate your own API client {#generate-your-own-api-client} 1. Navigate to the API documentation page. 2. Download the Payment Initiation API specification (OpenAPI or Swagger). 3. Generate and configure an API client for this API. 4. Configure your client using our [client libraries](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/#client-libraries). Note: For a detailed step-by-step guide, refer to the [Generating and Configuring a Mastercard API Client](https://developer.mastercard.com/platform/documentation/security-and-authentication/generating-and-configuring-a-mastercard-api-client/). ### Testing the service {#testing-the-service} The service can be tested using the following methods: * **Reference Application:** Use the Reference Application to test the service. For details, refer to the [Reference Application](https://developer.mastercard.com/payment-initiation-api/documentation/developer-tools/reference-app/index.md) page. * **Insomnia:** Use Insomnia to test the APIs by following the [Insomnia Tutorial](https://developer.mastercard.com/platform/tutorial/use-insomnia-rest-client-for-mastercard-apis/). * **curl or a custom client:** Use the [Testing](https://developer.mastercard.com/payment-initiation-api/documentation/testing/index.md) page for test cases and additional examples. ## Step 5: Promote the same project to Production {#step-5-promote-the-same-project-to-production} After testing the implementation in the Sandbox environments, the next step is to **Move to Production**. ### Steps to Moving to Production {#steps-to-moving-to-production} 1. Within your project, select **Request Production Access** . ![Screenshot of the Mastercard Developers project summary page showing the sandbox client ID, the list of project APIs with Payment Initiation marked as ready in Sandbox, and options to add a new API or delete the project.](https://static.developer.mastercard.com/content/payment-initiation-api/uploads/summary-overview.png) 2. Provide the service details by filling out the form and select **Proceed** . ![Screenshot of the Service Details page in Mastercard Developers showing required fields for configuring the Payment Initiation service, including business details, address, organization identifier, customer identifiers, and options for initiating payment instruction.](https://static.developer.mastercard.com/content/payment-initiation-api/uploads/service-details-production.png) | Field | Description | Example value | Required? | |------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------|-----------| | Legal Business Name | Identifies the legal business name of the Buyer receiving the payment. | payment-initiation-demo | Yes | | Legal Address Line 1 | Business address line 1 | 2200 Mastercard Blvd | Yes | | Legal Address Line 2 | Business address line 2 | AddressLine2 | No | | Legal Address Line 3 | Business address line 3 | 2200 Mastercard Blvd | No | | Town Name | Identifies the name of the city or geographical location of the address. | New York | Yes | | Country Subdivision/State | Identifies the subdivision within a country where the business is located, such as the state, region, or county. | Vatican City | Yes | | Postcode | Identifies the mailing or ZIP code for the business. | 22043 | Yes | | Country | Identifies the country where the business is located. | United States of America | Yes | | Organization Identifier Type | Organization or identification type. | TXID | Yes | | Organization Identifier | Organization or tax identification number. | 123456789 | Yes | | Customer Identifier (CID) | A master identification number for all Mastercard customers. It can be 6-11 digits in length, but all CIDs issued today are 6 digits in length. A CID identifies a customer's unique legal entity. If a customer is defined by their legal entity, each customer should have one CID. If a customer has multiple legal entities, they can have multiple CIDs, with one for each entity. There is no limit to the number of legal entities that a customer can have. CIDs for unique legal entities under one customer can be tied together with a legal grandparent number. Currently some customers have multiple CIDs for one legal entity. | 123456 | Yes | | Customer ICA | Interbank Card Association. Used for agent identification in all service requests for core operations. | 123456 | Yes | | Will you be initiating the API requests to make payments on-behalf of a Buyer? | The answer to this question helps identify if you are a direct or indirect Commercial Direct Payments customer. **Note: If you are unsure what type of user you are, refer to the tip below.** | Yes | Yes | | Will you be initiating the API requests to make payments on-behalf of a Payment Agent? If yes, click the appropriate role from the list below. | A customer service provider is defined as a person (entity) that performs Program Service that is an agent of the Customer that receives or otherwise benefits from Program Service, whether directly or indirectly, performed by such Service Provider. A Mastercard Vendor is defined as a person (entity) that provides services to Mastercard. If you are not transacting on behalf of a Buyer, you must select either Customer Service Provider or Mastercard Vendor. **Note: If you are unsure what type of user you are, refer to the tip below.** | N/A | Yes | | Notification URL | A unique resource location for Commercial Direct Payments service to send event notifications. | `https://demonotificationurl.com` | Yes | Tip: Prospective users should review the agent types outlined in the table below. | Agent type | Initiate payments? | Customer type | |------------------------------------------|--------------------|---------------------------| | Debtor Agent | Yes | N/A | | Mastercard Service Provider | No | Mastercard Vendor | | Processor | No | Customer Service Provider | | Debtor Agent Processor | Yes | Customer Service Provider | | Debtor Agent Mastercard Service Provider | Yes | Mastercard Vendor | 3. Create and securely store a key alias and keystore password for the OAuth 1.0a project keys, then select **Proceed** . ![Project credentials step in the Request Production Access flow, showing OAuth 1.0a project keys with fields for key alias and keystore password, and navigation buttons to skip, go back, or proceed.](https://static.developer.mastercard.com/content/payment-initiation-api/uploads/project-credentials-prod.png) 4. Create and record a key alias and keystore password for the encryption keys, then select **Update Project** . ![Project credentials screen showing OAuth 1.0a project keys with fields for key alias and keystore password, and a Proceed button.](https://static.developer.mastercard.com/content/payment-initiation-api/uploads/additional-credentials-prod.png) 5. Confirm that the Production keys are generated, select **Download key file** and save it securely. ![Project update screen showing progress steps for generating keys, updating the project, and packing keys, with a download key file option.](https://static.developer.mastercard.com/content/payment-initiation-api/uploads/request-production-access-updated.png) Note: Production credentials are generated instantaneously, but they still need to be approved for Production environment access before you can go live. Once your Production access request has been reviewed, you will receive a notification confirming your access has been approved or denied. For the complete onboarding process including contracting, sandbox (MTF), service‑level agreements (SLAs), and escalation procedures see the [Onboarding Checklist](https://developer.mastercard.com/payment-initiation-api/documentation/tutorial-and-guide/onboarding-checklist/index.md). ### Next Steps {#next-steps} Continue with the documentation that matches your next task: * [API Reference](https://developer.mastercard.com/payment-initiation-api/documentation/api-reference/index.md) for endpoint details * [API Basics](https://developer.mastercard.com/payment-initiation-api/documentation/api-basics/index.md) for authentication, encryption, and client configuration * [Testing](https://developer.mastercard.com/payment-initiation-api/documentation/testing/index.md) for additional request scenarios * [Onboarding Checklist](https://developer.mastercard.com/payment-initiation-api/documentation/tutorial-and-guide/onboarding-checklist/index.md) for the full operational go-live process