# API basics source: https://developer.mastercard.com/mastercard-supplier-payment-agent/documentation/api-basics/index.md The Supplier Payment Agent APIs are HTTP-based RESTful APIs that use OAuth 1.0a for authorization. Mastercard provides a sandbox and a production environment to access this API using API keys. To start using the Business Payment Service APIs, you must first create a project and add the Supplier Payment Agent APIs into the Mastercard Test Facility (MTF). For information on how to do so, refer to the [Getting your credentials](https://developer.mastercard.com/mastercard-supplier-payment-agent/documentation/tutorials_guides/guides/impl-guide/index.md) guide. Once created, you will have access to MTF, which you can use to test OAuth 1.0a authentication and validate that requests are correctly formatted. ## Authentication {#authentication} You can access the Business Payment Service APIs through the Mastercard Developers API Gateway, which uses the OAuth standard for access delegation. Mastercard Track Business Payment Service uses OAuth 1.0a for authenticating the API clients. This requires every request you send to Mastercard to be signed with an RSA private key. A private-public RSA key pair must be generated consisting of: * A private key for the OAuth signature for API requests. It is recommended to keep the private key in a password-protected or hardware keystore. * A public key shared with Mastercard during the project setup process through either a certificate signing request (CSR) or the API Key Generator. Mastercard uses the public key to verify the OAuth signature that is provided on every API call. Requests with a body must be signed using the [Google request body hash extension](https://tools.ietf.org/id/draft-eaton-oauth-bodyhash-00.html) for OAuth. ## OAuth keys \& authentication libraries {#oauth-keys--authentication-libraries} OAuth Keys for your project can be set up in your [Developer dashboard](https://developer.mastercard.com/dashboard). For more information see: [Authentication Requirements for Mastercard Services](https://developer.mastercard.com/platform/documentation/security-and-authentication/using-oauth-1a-to-access-mastercard-apis/). Client authentication libraries can be found on [GitHub](https://github.com/Mastercard?&q=oauth), with how-to information provided in the [README.md](https://github.com/Mastercard/oauth1-signer-java/blob/master/README.md) files. ## Encryption {#encryption} To ensure safe data transfer between you and Mastercard Track Business Payment Service APIs, you must encrypt specific fields within payloads containing sensitive information. Mastercard further encrypts all sensitive information. As a Supplier Payment Agent, you handle sensitive business daily, and you need to decrypt the sensitive payment instruction data you retrieve. For more information Mastercard's payload encryption, refer to [Securing sensitive data using payload encryption](https://developer.mastercard.com/platform/documentation/security-and-authentication/securing-sensitive-data-using-payload-encryption/). ### Encryption error reason codes {#encryption-error-reason-codes} You may receive one of the following errors when decrypting the `card` object. | Message code | Scenario | Description | |--------------|-------------------------|--------------------------------------------------------------------------------------------------------------------------| | EXPIRED_KEY | If the Keys are expired | The encryption key used to encrypt/decrypt has expired. Please renew your encryption keys through Mastercard Developers. | ## Event notification security {#event-notification-security} Event notifications provide a mechanism for Business Payment Service to notify you when a new event is triggered. To secure these event notifications and provide you with the ability to trust Business Payment Service before receiving these notifications, Mastercard supports Mutual TLS (MTLS) authentication. Mastercard recommends customers rely on the CA trusted method of verification. This approach enables comparatively smoother implementation or renewal of certificates in future for customers. ## Environment descriptions {#environment-descriptions} You must work with the Business Payment Service onboarding team to simulate end-to-end testing. | Environment name | Description | Link | |--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------| | Mastercard Test Facility (MTF) | The pre-production test environment containing the latest pre-release version of the real APIs, intended for full integration testing prior to moving to production. | `https://sandbox.api.mastercard.com` | | Production | The full production environment containing the latest production API release. | `https://api.mastercard.com` | ## Glossary of terms {#glossary-of-terms} | Terms | Definition | |----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | API | Application Programming Interface. | | Array | Data structure consisting of a collection of similar elements (values or variables), each identified by at least one array index or key. | | Boolean | Data type with only two possible states: true or false. | | Buyer | The entity making payments to a Supplier to procure goods or services. | | BPA | Buyer Payment Agent. The entity acting on behalf of a Buyer to submit payment instructions. A BPA can include procure-to-pay networks, banks, and other specialty players like accounts payable automation companies. | | Client | Client application consuming the STP API. | | ClientRef | Client Reference. Unique ID specified by the client. | | CSP | Customer Service Provider. 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. | | Future dated payment | Informs the payment beneficiary (e.g. Supplier or Funder) of the specific date you intend to disburse funds. | | HTTP | Hypertext Transfer Protocol. | | Integer | Whole number that contains no decimals or fractions. | | ICA | Interbank Card Association. Used for agent identification in all service requests for core operations. | | JSON | JavaScript Object Notation. | | OAuth | Open protocol to allow secure authorization in a simple and standard method from web, mobile, and desktop applications. | | REST | Representational State Transfer. | | Payment instruction | Includes payment information and remittance data. | | SLA | Service-Level Agreement. A commitment from the BPA and SPA to share the required data needed to participate and switch payment instructions through the Business Payment Service network within a specified time period. | | String | Sequence of characters. | | Supplier | The entity receiving payments from a Buyer for selling goods or services. | | SPA | Supplier Payment Agent. The entity acting on behalf of a Supplier to retrieve and process payment instructions. An SPA can include procure-to-pay networks, banks, and other specialty players like accounts receivable automation companies. | | URI | Uniform Resource Identifier. | | URL | Uniform Resource Locator. | | UI | User Interface. |