Get Started
Follow the tasks on this page to register for OAuth 2.0 and integrate to the method that matches how your client obtains consent to access another organization's data.
Integration Methods
Before You Begin
Complete Steps 1 – 3 in the technology partner Go Live page before beginning to set up OAuth 2.0. The steps explain how to complete these requirements:
- Sign up your organization as a technology partner in order to create a account.
- Register your Solution in in order to receive your Solution ID.
- Enable your system to send and receive REST API messages, which includes creating your API keys and setting up your system to construct JWTs.
In addition to the above requirements, verify that your account has OAuth Application Management permissions. For more information, contact your account manager or customer support.
Choose Your Integration Method
Choose the integration method that matches how your client obtains consent to access another organization's data.
Compare the three integration methods
offers three OAuth 2.0 integration methods. The method you integrate to is determined by your organization type and how your client obtains consent from another organization to access their data.
The On-Behalf-Of integration method uses the authorization code grant. A merchant or user signs in to the and grants your client permission to act on their behalf. This integration method is also known as on-behalf-of, or OBO.
This table lists the organization types that can use the On-Behalf-Of integration method and a business example for each:
| Organization Type | Example |
|---|---|
| AI agent enabler | An AI assistant performs payment operations, dispute handling, or reconciliation on behalf of a consenting merchant, limited to the permissions that the merchant approves. |
| Partner acquirer or partner reseller | A bank portal initiates refunds or views reporting data on behalf of its merchants. |
| Technology partner | A SaaS platform accesses payment and reporting APIs on behalf of its merchants. |
| Merchant | A merchant grants a trusted client permission to access account data or perform permitted API operations on the merchant's behalf. |
The Machine-to-Machine (M2M) integration method uses the client credentials grant. Your system accesses APIs without user sign-in or merchant consent during the flow. The client and authenticate each other before issues an access token.
This table lists the organization types that can use the Machine-to-Machine integration method and a business example for each:
| Organization Type | Example |
|---|---|
| AI agent enabler | An AI coding agent or automated process connects to MCP to perform reconciliation, reporting, or scheduled payment operations. |
| Merchant | A merchant ERP or reconciliation system accesses payment APIs securely with OAuth tokens instead of static API keys. |
| Partner acquirer or partner reseller | An enterprise reporting platform or AI automation system aggregates data across multiple merchants. |
| Technology partner | A Remote MCP integration or embedded component calls APIs as a system client. |
The OpenID Connect (OIDC) integration method uses the authorization code grant. Your client authenticates users with one of the supported sign-in methods:
- Sign in through the .
- Single sign-on, or SSO.
- A federated identity relationship between and another platform.
This table lists the organization types that can use the OpenID Connect integration method and a business example for each:
| Organization Type | Example |
|---|---|
| Partner acquirer or partner reseller | A bank platform uses federated login with or coordinates sign-in across multiple merchants. |
| Technology partner | A partner portal uses SSO so merchants can sign in with their credentials. |
OAuth 2.0 Integration Methods
Choose a method to see the remaining setup steps.
How the Authorization Code Grant Works
Use the authorization code grant when another organization must sign in and grant consent for your application to access the APIs on their behalf. Your application can only perform tasks determined by the scopes set by the consenting organization. To act on behalf of an organization, your application must request an access token and then continually request refresh tokens.
These are the tasks that all organizations and applications must complete to successfully use delegated access:
- The merchant accesses your application to begin integrating to it.
- Your application redirects the merchant to the using a URL that you configured.
- The merchant logs in and grants your application permission to act on their behalf.
- redirects the merchant to your application using the URL you registered during signup with an authorization code appended to the URL.
- Your application receives an authorization code that is appended to the redirect URL.
- Your application uses the authorization code to request an access and refresh token from .
- Your application uses the access token to send API requests to on behalf of the merchant.
- Your application uses the refresh token to request a new set of access and refresh tokens when your current access token expires. Request new access and refresh tokens as often as you need to maintain your merchant access.
Set Up mTLS Client Authentication
You must set up secure client authentication for to verify your application when it requests access tokens. When using this integration method, you must use mutual TLS (mTLS) client authentication. Mutual TLS client authentication provides bidirectional authentication between you and . When your application sends an API request, it includes an authentication certificate. validates the certificate, which verifies your application's identity, and then issues you an access token and refresh token.
Supported Certificates
Obtain a supported certificate from the DigiCert Certificate Authority (CA) or Visa.
To request a DigiCert certificate, see the DigiCert support page: https://www.digicert.com/contact-us
offers the free VICA10 CA certificate. It is ideal for testing and is self-managed by the root certificate authority – G2. To request a VICA10 certificate, contact customer support.
| Certificate Authority | Supported Certificates |
|---|---|
| DigiCert CAs |
|
| Visa CA |
|
Set Up mTLS
Complete these tasks to set up mTLS client authentication:
Generate a private key in your system.
Extract a certificate signing request (CSR) from your private key.
Request a certificate from the DigiCert certificate authority (CA). You submit your CSR in this request.
For a list of the supported certificates, see Supported Certificates.
Receive a certificate from DigiCert after your request is validated.
Submit your certificate in the , which generates a P12 certificate for you to download and use in your integration.
Submit Your mTLS Certificate
Follow these steps to submit your mTLS certificate file:
On the left navigation panel, choose Payment Configuration > Key Management.
Click + Generate key on the Key Management page.
Choose Mutual Authentication and then click Generate key.
The Key Generation page appears.
Enter your certificate in the text box and then click Download key .
The Key Generation page appears.
Create a password for the certificate by entering one into the New Password and Confirm Password fields. Click Generate key.
To submit another certificate, click Generate another key. To view all of your submitted certificates and created keys, go to the Key Management page.
To test mTLS client authentication before you request a DigiCert certificate, contact customer support.
Obtain Merchant Authorization
Before your application can send API requests on behalf of a merchant, the merchant must grant your application permission to do so. To obtain permission, your application must redirect the merchant to the . The merchant can then log in to their account and review the scope of permissions your application is requesting. After the merchant approves your application to perform the listed permissions, redirects the merchant to your application. The redirect URL that uses is determined by the URLs you submitted when registering for OAuth 2.0. also appends the redirect URL with an authorization code and state status. The authorization code is necessary to request an access token.
Create and Implement a Redirect URL
Follow these steps to construct the URL that your application can use to redirect merchants to the where they can grant permissions:
Set the host domain for the redirect URL:
- Production: /ebc2/
- Test: /ebc2/
Append the host domain with a question mark (
?) to designate the start of the query-string.Include these query-parameters with an ampersand (
&) after each consecutive parameter. Set the required parameters in the order that they are listed./ebc2/oauth2/authorize?response_type=code&client_id={yourClientId}&code_challenge={codeChallenge}&code_challenge_method=S256&redirect_uri={yourCallbackUrl}&state={state}/ebc2/oauth2/authorize?response_type=code&client_id={yourClientId}&code_challenge={codeChallenge}&code_challenge_method=S256&redirect_uri={yourCallbackUrl}&state={state}The readable example is formatted in a readable structure and is not intended to be used. The encoded example is formatted correctly for implementation.
Request Parameter Description response_typeSet to code.client_idThe client identifier issued by when you registered your application. Example: client_id=abc123xyzredirect_uriThe URI to which the merchant is redirected after granting your application authorization in the . Example: redirect_uri=https://app.example. com/callback stateA value your application generates that is used as CSRF protection. The generated value must be unique and cryptographically random. After the merchant grants your application authorization, redirects the merchant to your application and appends this value to the redirect URL. Example: state=af0ifjsldkjcode_challengeThe PKCE code challenge is a SHA-256 hash of the code verifier, encoded using Base64URL. For more information about generating a code verifier and its code challenge value, see Generate a Code Verifier and Code Challenge. code_challenge_methodSet to S256.Set your application to use your constructed URL to redirect merchants who want to grant permissions.
redirects the merchant back to your application after the merchant completes granting permissions. The URL used to redirect the merchant to your application is the URL you submitted during registration. It includes these response parameters appended to it:
your_registered_redirect_URL?code={authorization_code}&state={state}Response Parameter Description codeThe authorization code that is used to request access and refresh tokens. It expires ten minutes after being issued. If the code expires, you must request merchant authorization again. stateThe CSRF protection value that you sent in the stateparameter. If this value does not match the value you sent, reject the request.
Redirect Error Response Codes
These are possible error responses you can receive from unsuccessful requests. Use this reference to troubleshoot unsuccessful requests.
| HTTP Status | Error Code | Description |
|---|---|---|
400 | http_message_not_readable | The request body cannot be parsed. |
400 | invalid_request | The request is malformed, contains invalid syntax, or is missing one or more required parameters. |
400 | invalid_client | Client authentication failed, or the client is not recognized by the authorization server. |
400 | invalid_grant | The authorization code is invalid, expired, previously used, or does not match the redirect URI or client that initiated the authorization request. |
400 | invalid_scope | The requested scope is invalid, unknown, malformed, or not permitted for the client. |
403 | access_denied | The merchant or user denied the authorization request, or the authorization server rejected the request. |
403 | insufficient_scope | The access token does not include the scope required to access the requested resource. |
Generate a Code Verifier and Code Challenge
The code verifier is a Proof Key for Code Exchange (PKCE) value used to securely link the authorization request to the token request. Its value is a cryptographic random string that your client generates. After creating the code verifier, create a code challenge. A code challenge is a SHA-256-hash value of the code verifier, which is encoded using Base64URL. The code challenge is included in the authorization request. When you request access and refresh tokens, you must include the code verifier to confirm your client's identity.
Follow these steps to generate the values:
To create a code verifier, run one of these code snippets in a terminal:
import java.security.SecureRandom;import java.util.Base64;SecureRandom sr = new SecureRandom();byte[] code = new byte[32];sr.nextBytes(code);String codeVerifier = Base64.getUrlEncoder() .withoutPadding() .encodeToString(code);// Use codeVerifier as the code verifier parameter value.// Dependency: Node.js crypto moduleconst crypto = require('crypto');function base64URLEncode(buffer) { return buffer.toString('base64') .replace(/\+/g, '-') .replace(/\//g, '_') .replace(/=/g, '');}const code_verifier = base64URLEncode(crypto.randomBytes(32));// Use code_verifier as the code verifier parameter value.Run one of these code snippets and include the code verifier value that you generated:
import java.nio.charset.StandardCharsets;import java.security.MessageDigest;import java.security.SecureRandom;import java.util.Base64;SecureRandom sr = new SecureRandom();byte[] code = new byte[32];sr.nextBytes(code);String codeVerifier = Base64.getUrlEncoder() .withoutPadding() .encodeToString(code);byte[] bytes = codeVerifier.getBytes(StandardCharsets.US_ASCII);MessageDigest md = MessageDigest.getInstance("SHA-256");byte[] digest = md.digest(bytes);String codeChallenge = Base64.getUrlEncoder() .withoutPadding() .encodeToString(digest);// Use codeChallenge as the code challenge parameter value.// Use "S256" as the code challenge method parameter value.const crypto = require('crypto');function base64URLEncode(buffer) { return buffer.toString('base64') .replace(/\+/g, '-') .replace(/\//g, '_') .replace(/=/g, '');}function sha256(buffer) { return crypto.createHash('sha256').update(buffer).digest();}const code_verifier = base64URLEncode(crypto.randomBytes(32));const code_challenge = base64URLEncode(sha256(code_verifier));Set the
code_challengeparameter to the generated code challenge value.Store the original code verifier value temporarily. You must send the same code verifier in your access token request.
Request Access and Refresh Tokens
Use the authorization code that you received to request an access token and a refresh token. Your OAuth application uses the access token to send API requests on behalf of the merchant. The access token is valid for fifteen minutes. When it expires, your application uses the refresh token to request a new access token as often as needed. If the refresh token expires before you can request a new one, you must obtain merchant authorization again. A refresh token is valid for thirty days. When you need to request a new set of tokens, see Renew the Access and Refresh Tokens.
Endpoint
POST /oauth2/v4/token
POST /oauth2/v4/token
Set the Content-Type HTTP header to application/x-www-form-urlencoded.
Example: Request an Access Token
POST /oauth2/v4/tokenContent-Type: application/x-www-form-urlencodedgrant_type=authorization_code&code={authorization_code}&redirect_uri={redirect_uri}&client_id={client_id}&client_secret={client_secret}&code_verifier={code_verifier}{ "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6Ikp...", "token_type": "bearer", "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "expires_in": 900, "refresh_token_expires_in": 2592000, "client_status": "active"}Request Body Parameters
| Body Parameter | Description |
|---|---|
grant_type | Set to authorization_code. |
code | The authorization code received from the authorization response. |
redirect_uri | The redirect URI that is registered to the OAuth application. |
client_id | The client ID that is issued during OAuth registration for your application. |
client_secret | The client secret that is issued during OAuth registration for your application. |
code_verifier | The code verifier that was created during the authorization request. It is a PKCE verifier. For more information, see Generate a Code Verifier and Code Challenge. |
Response Body Fields
A successful response consists of these body fields and values:
| Field | Description |
|---|---|
access_token | The access token that is used to authenticate API requests. You must include this in the Authorization request header as the bearer token. |
client_status | The status of the client, such as active. |
expires_in | The amount of time the access token is valid in seconds from the time the token is created. |
refresh_token | The refresh token that is used to maintain access when the initial access token expires. |
refresh_token_expires_in | The amount of time the refresh token is valid in seconds from the time the token is created. |
token_type | The type of token that is issued. |
Token Error Response Codes
These are possible error responses you can receive from unsuccessful requests. Use this reference to troubleshoot unsuccessful requests.
| HTTP Status | Error Code | Description |
|---|---|---|
| 400 Bad Request | invalid_request | The request is missing a required parameter, includes an unsupported parameter value, repeats a parameter, or is otherwise malformed. |
| 400 Bad Request | invalid_client | Client authentication failed: the client_id is unknown, or the client credentials are missing or malformed. |
| 400 Bad Request | invalid_grant | The supplied authorization grant or refresh token is invalid, expired, revoked, or does not match the redirect URI used in the authorization request. |
| 400 Bad Request | invalid_scope | The requested scope is unknown, malformed, or exceeds the scope granted to the client. |
| 400 Bad Request | http_message_not_readable | The request body could not be parsed, typically because of malformed JSON or an incorrect Content-Type header. |
| 401 Unauthorized | — | Client authentication failed. |
| 500 Internal Server Error | — | An unexpected error occurred while processing the request. |
Send API Requests on Behalf of the Merchant
After you receive an access token, you can send API requests on behalf of the merchant. When you send a request, include the access token in the Authorization header as a bearer token. For more information about constructing your API requests, see Construct a Request Using a JWT.
Set <access_token> to the access token value you received in Step 4.
curl --request POST \ --url /pts/v2/payments \ --header 'Authorization: Bearer <access_token>' \ --header 'content-type: application/json' \ --data '{ API_request_message }'curl --request POST \ --url /pts/v2/payments \ --header 'Authorization: Bearer <access_token>' \ --header 'content-type: application/json' \ --data '{ API_request_message }'Renew the Access and Refresh Tokens
Request a new access and refresh token after your current access token expires. Request new tokens as often as you need to maintain your merchant authorization. When you receive a new set of tokens, the previous tokens become invalid. A refresh token is valid for thirty days. If your current refresh token expires before you can request a new set of tokens, the merchant must log in to their account and grant you authorization again.
Endpoint
POST /oauth2/v4/token
POST /oauth2/v4/token
Set the Content-Type HTTP header to application/x-www-form-urlencoded.
Example: Renew the Tokens
POST /oauth2/v4/tokenContent-Type: application/x-www-form-urlencodedgrant_type=refresh_token&refresh_token=eyJraWQiOiI4MGI2ZDJjM2NkZGRkMm...&client_id={client_id}&client_secret={client_secret}{ "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6Ikp...", "token_type": "bearer", "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "expires_in": 900, "refresh_token_expires_in": 2592000, "client_status": "active"}Renewal Request Body Parameters
| Body Parameter | Description |
|---|---|
client_id | The client ID that is issued during OAuth registration for your application. |
client_secret | The client secret that is issued during OAuth registration for your application. |
grant_type | Set to refresh_token. |
refresh_token | Set to the current valid refresh token. |
Next Steps
How the Client Credentials Grant Works
Use the client credentials grant OAuth method if you want your application to access the APIs without requiring a user to log in to the application or a merchant to grant it permission. This method enables your application to automatically authenticate as itself using the gateway.
This integration method requires your application to request an access token using the API.
These are the tasks that your application must complete to successfully authenticate as a system client and send API requests:
- Your application signs a client assertion, which is a JWT signed with the private key from your P12 certificate.
- Your application sends the client assertion to to request an access token.
- validates the client assertion, which verifies your application's identity.
- responds with an access token. The response does not include a refresh token.
- Your application uses the access token to send API requests to on behalf of the merchant.
- Your application signs a new client assertion and requests a new access token when the current access token expires. Access tokens expire after fifteen minutes, so request new access tokens as often as you need to maintain your merchant access.
Available Business Purposes
The client credentials grant OAuth method is available for these business purposes:
- Embedded components: a portfolio manager can embed -hosted UI modules into their application or platform, such as merchant boarding, Unified Checkout, transaction search, reporting, key management, or webhooks.
- Remote MCP direct access: a merchant system or AI agent accesses APIs automatically without a user needing to log in and approve permissions.
Your purpose for using the Machine-to-Machine integration determines specific values you must set when constructing a client assertion.
Create a Client Assertion JWT
Before your system can request permission to act on behalf of another organization, your system must create a client assertion. A client assertion is a signed JWT string. Your system must include this string as the client_assertion header claim value when it requests an access and refresh token.
Create the JWT Header
Create a JWT header using these header fields:
| Header Field | Description |
|---|---|
alg | The asymmetric algorithm you use to sign the token header. These algorithms are supported: RS256 (default), RS384, RS512, PS256, PS384, and PS512. |
kid | The key ID you use to digitally sign the JWT. It must be registered with the authorizing server. It is the key ID from your P12 certificate. |
typ | The token type. Set to JWT. |
{ "alg": "RS256", "kid": "your_p12_key_id", "typ": "JWT"}Construct the JWT Payload
Construct the JWT payload as a JSON object that contains these required body claims:
| Body Claim Field | Description |
|---|---|
aud | Set to the token endpoint. This is the audience of the JWT. |
exp | The expiration time, in Unix epoch seconds. Keep the amount of time the token is valid short. |
iat | The time at which the token is issued in Unix epoch seconds. |
iss | The issuer of the JWT. For embedded components, set to the partner organization ID. For remote MCP direct access, set to the merchant ID. |
jti | A unique JWT identifier, such as a UUID. This value must be unique for each request to help prevent replay attacks. |
scope | The scopes requested by your application. For embedded components, set to boarding. For remote MCP direct access, set to transaction_search user_management. |
sub | Subject of the JWT. Set to your application's client ID, which is the client_id value. |
v-c-merchant-id | The organization or merchant that the access token is created for. For embedded components, set to the portfolio organization ID or merchant ID. For remote MCP direct access, set to the merchant ID. |
v-c-response-mle-kid | The key identifier for message-level encryption (MLE) of the response. |
{ "iss": "partner_org_id", "sub": "client_id", "aud": "/oauth2/v4/token", "jti": "f3d0a7c2-5e8b-4c9a-b1d3-e4f5a6b7c8d9", "exp": 1699565100, "iat": 1699564800, "v-c-merchant-id": "Portfolio Org ID or Merchant ID", "scope": "boarding", "v-c-response-mle-kid": "50622d914e4bc08352af3d50bce77120"}Encode the Header and Payload
Encode the JWT header and payload using Base64URL.
{base64url_encoded_header}{base64url_encoded_payload}Create the Signing Input
Create the signing input by combining the encoded header and encoded payload.
{base64url_encoded_header}.{base64url_encoded_payload}Sign the JWT
Sign the JWT with the private key from your P12 certificate. Use the P12 certificate that is registered to your OAuth application, platform, or system.
This is a conceptual example for how to obtain the encoded signature using Base64URL:
sign("{base64url_header}.{base64url_payload}", private_key) = {base64url_encoded_signature}Combine the Segments
Combine the encoded header, payload, and signature with the period character (.) separating each variable. This creates the signed client assertion JWT.
{base64url__encoded_header}.{base64url_encoded_payload}.{base64url_encoded_signature}eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJtZXJjaGFudF9pZCIsInN1YiI6ImNsaWVudF9pZCJ9.XYabc123...Set the Client Assertion Parameter
Set the client_assertion request parameter in the access token request to the JWT string value.
client_assertion={signed_jwt}POST /oauth2/v4/tokenContent-Type: application/x-www-form-urlencodedgrant_type=client_credentials&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={signed_jwt}Request an Access Token
Enable your system to request an access token from . An access token enables your system to send API requests on behalf of another organization. When your system sends this request, the signed JWT that contains the request must also contain a client assertion.
Endpoint
POST /oauth2/v4/token
POST /oauth2/v4/token
Set the Content-Type HTTP header to application/x-www-form-urlencoded.
Example: Request an Access Token
POST /oauth2/v4/tokenContent-Type: application/x-www-form-urlencodedgrant_type=client_credentials&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer&client_assertion={signed_jwt}{ "access_token": "eyJh.bGciOi_EXAMPLE_ACCESS_TOKEN_adQssw5c", "token_type": "bearer", "expires_in": 900, "client_status": "active"}Access Token Request Parameters
| Request Parameter | Description |
|---|---|
grant_type | Set to client_credentials. |
client_assertion_type | Set to urn:ietf:params:oauth:client-assertion-type:jwt-bearer. |
client_assertion | The signed JWT client assertion. For more information, see Create the JWT Header. |
Access Token Response Fields
| Parameter | Description |
|---|---|
access_token | The token used to authenticate API requests. Include this value in the Authorization header as a bearer token. |
client_status | The status of the client, such as active. |
expires_in | The amount of time an access token is valid after being issued, in seconds. |
token_type | The type of token issued, such as bearer. |
Send a Request on Behalf of a Merchant
After you receive an access token, you can send API requests on behalf of the merchant. When you send a request, include the access token in the Authorization header as a bearer token. For more information about constructing your API requests, see Construct a Request Using a JWT.
Set <access_token> to the access token value you received in Step 3.
curl --request POST \ --url /pts/v2/payments \ --header 'Authorization: Bearer <access_token>' \ --header 'content-type: application/json' \ --data '{ API_request_message }'curl --request POST \ --url /pts/v2/payments \ --header 'Authorization: Bearer <access_token>' \ --header 'content-type: application/json' \ --data '{ API_request_message }'Renew the Access Token
Access tokens expire after fifteen minutes. To continue sending API requests on behalf of a merchant, request a new access token before the current token expires. When a new token is issued, the previous token becomes invalid.
To request a new access token, sign a new client assertion as shown in Step 2, then send a new access token request as shown in Step 3.
Next Step
Authorization Code Grant Using OpenID Connect
Use the OpenID Connect (OIDC) integration method when you need to authenticate and verify a merchant or customer user who is logging into your platform. When a user attempts to log in to your platform, they are redirected to the to log in to their account. After logging in, sends you an ID token, access token, and refresh token. Use these credentials to continuously verify the user across your platform when they log in. If your application is not developed by , the user must grant consent to being redirected to the using an authorization screen.
Next Steps
Thanks for your feedback!
Last published: November 18, 2026