# API basics source: https://developer.mastercard.com/mastercard-buyer-payment-agent/documentation/api-basics/index.md The Buyer 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. 1. To start using Buyer Payment Agent (BPA) APIs, you must create a project and add the Buyer Payment Agent service into the Mastercard Test Facility (MTF). For information on how to do so, refer to the [Getting your Credentials](https://developer.mastercard.com/mastercard-buyer-payment-agent/documentation/tutorials_guides/guides/impl-guide/index.md) section. 2. Once created you will have access to the MTF, which you can use to test OAuth 1.0a authentication and validate that requests are correctly formatted. ## Authentication {#authentication} You can access the Buyer Payment Agent APIs through the Mastercard Developers API Gateway, which uses the OAuth standard for access delegation. The Mastercard Buyer Payment Agent uses OAuth 1.0a for authenticating the API clients. This requires every request that you send to Mastercard to be signed with an RSA private key. A private-public RSA key pair must be generated consisting of: 1. 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. 2. A public key shared with Mastercard during the project setup process through either a certificate signing request (CSR) or the API Key Generator. Mastercard will use 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 Buyer Payment Agent APIs, you must encrypt specific fields within payloads containing sensitive information. As a Buyer Payment Agent, you handle sensitive business daily, and as such, when you create and submit payment instruction data, you need to encrypt payload fields such as card information. You also need to decrypt the sensitive payment instruction data you retrieve. For more information on 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/). ## Event Notification Security {#event-notification-security} Event notifications provide a mechanism for the Buyer Payment Agent to notify you when a new event is triggered. To secure these event notifications and provide you with the ability to trust the Buyer Payment Agent before receiving these notifications, Mastercard supports Mutual TLS (MTLS) authentication. Mastercard recommends that 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 Buyer Payment Agent 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 | A 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. | | Buyer Payment Agent | Buyer Payment Agent. The entity acting on behalf of a Buyer to submit payment instructions. A Buyer Payment Agent 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. A unique ID specified by the client. | | CSP | Customer Service Provider. A person (entity) that performs Program Service 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 (for example, supplier or funder) of the specific date that you intend to disburse funds. | | HTTP | Hypertext Transfer Protocol. | | Integer | A 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 | Include payment information and remittance data. | | String | Sequence of characters. | | Supplier | The entity receiving payments from a Buyer for selling goods or services. | | SLA | Service-level agreement. The Buyer Payment Agent and Supplier Payment Agent service-level agreement (SLA) is a commitment from the Buyer Payment Agent and Supplier Payment Agent to share the required data needed to participate and switch payment instructions through the Buyer Payment Agent network within a specified time period. | | Supplier Payment Agent | Supplier Payment Agent. The entity acting on behalf of a Supplier to retrieve and process payment instructions. A supplier Payment Agent 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. |