Getting Started with Purse API

Welcome to the Purse API Integration Guide!
This guide will walk you through the essential steps to integrate Purse API into your system.

1. Prerequisites

Before starting, ensure you have:

• A Purse API account giving your API credentials (ENTITY_ID, API_KEY, CLIENT_ID, CLIENT_SECRET).
• A server with HTTPS enabled for secure transactions.
• A basic understanding of REST APIs & JSON format.
• Your domain whitelisted by the Purse integration team.

Important

In order to use our solution in preproduction and production, you must whitelist your domain. Contact the Purse Integration Team to provide your required domain names. (Click here)

2. Authentication & API Credentials

Step 1: Setting Up Your Payment Environment

Purse will create one or multiple entities for your account.
Each entity represents a business unit that will process payments.

Entities can be organized hierarchically:

• Parent Entity → Can share credentials with child entities.
• Child Entities → Can inherit API credentials.

Example

• A company with multiple subsidiaries can have a "Parent Entity", which will share its API credentials with "Child Entities".

Once your access to the Purse dashboard is granted, you can retrieve your API credentials in the left menu under:

Support → API Keys

Definition of an entity can be found here.

Step 2: Understanding API Credentials

Each entity has four key credentials used for authentication:

Credential	Description	Length
ENTITY_ID	Unique identifier for your company on Purse services. Used in client session creation.	36 chars max
API_KEY	Used for client-side calls. Must be included in request headers as x-api-key.	36 chars max
CLIENT_ID	Unique identifier for your application on our services. Used in authentication.	100 chars max
CLIENT_SECRET	Used for server-side authentication. Only used in OAuth2 authentication requests.	100 chars max

Example : ENTITY_ID: 123e4567-e89b-12d3-a456-426614174000

Keep Credentials Private

Never expose your CLIENT_SECRET in frontend code or public repositories.

3. OAuth2 Authentication: Retrieving an Access Token

To make API requests, your server must be authenticated.
Purse API uses OAuth2 access tokens, which have a limited lifetime.

Step 1: Generate an Access Token

To obtain a token, send a request to /oauth/token with:

Required Headers:

• Content-Type: application/x-www-form-urlencoded
• Authorization: Basic BASIC_AUTH
• x-api-key: API_KEY

Authorization format

The Authorization header must follow this format:

Authorization: Basic <base64(CLIENT_ID:CLIENT_SECRET)>

• CLIENT_ID and CLIENT_SECRET are your API credentials.

Example (before encoding)
my-client-id:my-client-secret → Base64 → bXktY2xpZW50LWlkOm1...

Final header
Authorization: Basic bXktY2xpZW50LWlkOm15LWNsaWVudC1zZWNyZXQ=

Required Body Parameter:

• grant_type=client_credentials

Example Request (cURL)

curl -X POST "https://api.purse-sandbox.com/oauth/token"
     -H "Authorization: Basic \${BASIC_AUTH}"
     -H "Cache-Control: no-cache"
     -H "x-api-key: \${API_KEY}"
     --data-urlencode "grant_type=client_credentials"

Example Response

{
  "token_type": "Bearer",
  "expires_in": 14400,
  "access_token": "eyJraWQiO...",
  "scope": "payment-api"
}

4. Use the Access Token

Once you have a valid ACCESS_TOKEN, use it for all API requests.

Include it in the HTTP header:

Authorization: Bearer ${ACCESS_TOKEN}

Example API Call with Token

curl --X --location POST 'https://api.purse-sandbox.com/payment/v2/client-sessions'
--header 'x-api-key: YOUR_API_KEY'
--header 'Content-Type: application/json'
--data-raw '[...]'

Example Response

{
     "id": "aa30c404-bafe-4058-8d71-dec8e5a8b0f0",
     "status": "CREATED",
     "expires_at": "2025-04-08T14:10:31.616Z",
     "entity_id": "fcadf8f7-2d3d-4c71-8715-ddf2c1d3fe76",
     "amount": 12000,
     "currency": "EUR",
     "allow_future_usage": false,
     "capture_mode": "MANUAL",
     "integration_mode": "EMBEDDED",
     "shopper_redirection_url": "https://www.example.com",
     [...]
}

Keep your access token secure

Access tokens must remain confidential and must never be exposed in the browser or frontend code. They should only be used server-side, as they provide full access to your API credentials.

5. Token Expiry & Caching

Tokens expire after one hour in production. (Four hours in preproduction).

Token Expiry & Caching

Avoid generating a new token for each API call. This will exceed rate limits and block token creation for several minutes.

Best Practice

• Store the expires_in field from the authentication response.
• You should request a new token only 5 minutes before reaching the expires_in field limit set.

6. Next Steps

• Follow our step-by-step tutorials → Tutorials Section
• Explore API Reference → Purse API Documentation