API Integration¶

Direct API integration allows you to process payments programmatically using RESTful endpoints. This approach gives you full control over the payment flow and UI/UX.

🔐 Authentication¶

All API requests require a valid OAuth 2.0 access token:

HTTP Headers¶

Authorization: Bearer <access_token>
Content-Type: application/json

Obtaining an Access Token¶

Use the Client Credentials flow to obtain an access token. See Obtain Access Token for detailed instructions.

Your client_id and client_secret are available in your merchant dashboard.

💳 Processing Card Payments¶

Endpoint¶

POST /api/transactions/authorize

Data Encryption¶

All sensitive card data must be encrypted using your merchant public key before sending to the API.

Fields requiring encryption: - Card number - CVV - Expiration month - Expiration year

See the Encryption Example for detailed encryption instructions.

Basic Request Example¶

{
  "reference": "ORDER-123456",
  "terminal_id": "TERM001",
  "description": "Order payment",
  "currency": "EUR",
  "amount": 10000,
  "transaction_type": "AUTHORIZE",
  "payment_method": {
    "type": "card",
    "data": {
      "encrypted_card_number": "base64_encrypted_value",
      "encrypted_cvv": "base64_encrypted_value",
      "encrypted_expiration_month": "base64_encrypted_value",
      "encrypted_expiration_year": "base64_encrypted_value"
    }
  },
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "address": "123 Example Street",
    "city": "Sampletown",
    "country": "BA",
    "postal_code": "12345"
  },
  "browser_info": {
    "user_agent": "Mozilla/5.0...",
    "accept_header": "text/html,application/xhtml+xml...",
    "java_enabled": false,
    "color_depth": 24,
    "screen_height": 1080,
    "screen_width": 1920,
    "time_zone_offset": -120,
    "language": "en-US"
  },
  "metadata": {},
  "return_url": "https://merchant.example.com/return",
  "error_url": "https://merchant.example.com/error",
  "cancel_url": "https://merchant.example.com/cancel"
}

Network Token Payments (Apple Pay / Google Pay)¶

For merchants who handle wallet token decryption on their own infrastructure, the network-token payment method type allows you to send pre-decrypted network token data (DPAN, cryptogram, ECI) through the gateway.

This is useful for:

Apple Pay integrations where you decrypt the PKPaymentToken server-side
Google Pay integrations with CRYPTOGRAM_3DS or PAN_ONLY authentication
Direct TSP (Token Service Provider) integrations

Data Encryption¶

The following fields must be encrypted using your merchant public key (same key used for card encryption):

Token number (DPAN)
Expiration month
Expiration year
Cryptogram (when present)

The eci and source fields are sent as plain text.

See the Encryption Example for encryption instructions.

Request Example (Apple Pay)¶

{
  "reference": "ORDER-NT-001",
  "terminal_id": "TERM001",
  "description": "Apple Pay payment",
  "currency": "EUR",
  "amount": 10000,
  "transaction_type": "AUTHORIZE",
  "payment_method": {
    "type": "network-token",
    "data": {
      "encrypted_token_number": "base64_encrypted_dpan",
      "encrypted_expiration_month": "base64_encrypted_value",
      "encrypted_expiration_year": "base64_encrypted_value",
      "encrypted_cryptogram": "base64_encrypted_cryptogram",
      "eci": "05",
      "source": "apple-pay"
    }
  },
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "address": "123 Example Street",
    "city": "Sampletown",
    "country": "BA",
    "postal_code": "12345"
  },
  "browser_info": {
    "user_agent": "Mozilla/5.0...",
    "accept_header": "text/html,application/xhtml+xml...",
    "java_enabled": false,
    "color_depth": 24,
    "screen_height": 1080,
    "screen_width": 1920,
    "time_zone_offset": -120,
    "language": "en-US"
  },
  "metadata": {},
  "return_url": "https://merchant.example.com/return",
  "error_url": "https://merchant.example.com/error",
  "cancel_url": "https://merchant.example.com/cancel"
}

Request Example (Google Pay — PAN_ONLY)¶

When using Google Pay with PAN_ONLY authentication, the cryptogram and ECI are not present:

{
  "reference": "ORDER-NT-002",
  "terminal_id": "TERM001",
  "description": "Google Pay payment",
  "currency": "EUR",
  "amount": 5000,
  "transaction_type": "AUTHORIZE",
  "payment_method": {
    "type": "network-token",
    "data": {
      "encrypted_token_number": "base64_encrypted_dpan",
      "encrypted_expiration_month": "base64_encrypted_value",
      "encrypted_expiration_year": "base64_encrypted_value",
      "source": "google-pay"
    }
  },
  "customer": { ... },
  "browser_info": { ... },
  "metadata": {},
  "return_url": "https://merchant.example.com/return",
  "error_url": "https://merchant.example.com/error",
  "cancel_url": "https://merchant.example.com/cancel"
}

Network Token Payment Data Fields¶

Field	Type	Required	Encrypted	Description
`encrypted_token_number`	`string`	Yes	Yes	DPAN from the wallet or TSP
`encrypted_expiration_month`	`string`	Yes	Yes	Token expiration month (1–12)
`encrypted_expiration_year`	`string`	Yes	Yes	Token expiration year (4 digits, e.g. `2025`)
`encrypted_cryptogram`	`string`	No	Yes	Payment cryptogram (absent for PAN_ONLY)
`eci`	`string`	No	No	Electronic Commerce Indicator — required for CRYPTOGRAM_3DS, omitted for PAN_ONLY. Valid values: `00`, `01`, `02`, `05`, `06`, `07`
`source`	`string`	No	No	Token origin: `apple-pay`, `google-pay`, or `network-token`. Defaults to `network-token` if omitted

For detailed information about network tokens, see the Network Token Reference.

💾 Saving Cards for Future Payments¶

The API supports tokenization, allowing you to save payment cards for future transactions. This is useful for:

Subscription or recurring payments
One-click checkout experiences
Repeat customer transactions

Requirements for Card Tokenization¶

Before using tokenization, ensure:

Tokenization is enabled at the merchant level (contact your payment platform administrator)
Customer exists (if using customer.id): The customer must already exist in the Payment Platform
PCI compliance: Ensure your integration complies with PCI-DSS requirements

Saving a Card During Payment¶

To save a card for future use, include the tokenization object in your transaction request:

Request Example:

{
  "reference": "ORDER-123456",
  "terminal_id": "TERM001",
  "description": "Order payment",
  "currency": "EUR",
  "amount": 10000,
  "transaction_type": "AUTHORIZE",
  "payment_method": {
    "type": "card",
    "data": {
      "encrypted_card_number": "base64_encrypted_value",
      "encrypted_cvv": "base64_encrypted_value",
      "encrypted_expiration_month": "base64_encrypted_value",
      "encrypted_expiration_year": "base64_encrypted_value"
    }
  },
  "customer": {
    "id": "CUST123456",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "+1234567890",
    "address": "123 Example Street",
    "city": "Sampletown",
    "country": "BA",
    "postal_code": "12345"
  },
  "tokenization": {
    "save_card_for_future_payments": true
  },
  "browser_info": {
    "user_agent": "Mozilla/5.0...",
    "accept_header": "text/html,application/xhtml+xml...",
    "java_enabled": false,
    "color_depth": 24,
    "screen_height": 1080,
    "screen_width": 1920,
    "time_zone_offset": -120,
    "language": "en-US"
  },
  "metadata": {},
  "return_url": "https://merchant.example.com/return",
  "error_url": "https://merchant.example.com/error",
  "cancel_url": "https://merchant.example.com/cancel"
}

Tokenization Parameters¶

Field	Type	Description
`tokenization.save_card_for_future_payments`	`boolean`	If `true`, automatically saves the card for future use

⚠️ Compliance Note: When saving cards without explicit customer consent, ensure your terms of service and privacy policy inform customers that payment information will be stored for future use. Depending on your jurisdiction, this may have regulatory implications (GDPR, PCI-DSS, etc.).

Response with Saved Payment Method¶

When a card is successfully saved, the response includes a token in the payment_method object:

{
  "result": {
    "id": "TXN123456",
    "status": "APPROVED",
    "payment_method": {
      "method": "411111-******-1111",
      "type": "card",
      "brand": "VISA",
      "masked": "411111-******-1111",
      "token": "abc123def456ghi789"
    },
    ...
  }
}

The token value (e.g., abc123def456ghi789) is the payment method ID that can be used for future transactions.

🔑 Assigning Saved Payment Methods to a Customer¶

When saving a card, the customer.id field determines how the payment method is associated:

With `customer.id` (Recommended)¶

When you include customer.id in the request:

The saved payment method is automatically assigned to the specified customer
The customer must already exist in the Payment Platform
The payment method can be retrieved and used in future transactions for this customer
You can list all saved payment methods for a customer

Example:

{
  "reference": "ORDER-123456",
  "customer": {
    "id": "CUST123456",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com"
  },
  "tokenization": {
    "save_card_for_future_payments": true
  },
  ...
}

Without `customer.id`¶

When you do not include customer.id in the request:

The payment method is still saved and tokenized
The payment method remains unassociated with any customer
You can still use the payment method token for future transactions
The payment method cannot be associated with a customer later
You cannot retrieve this payment method through customer-based queries

Example:

{
  "reference": "ORDER-123456",
  "customer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com"
  },
  "tokenization": {
    "save_card_for_future_payments": true
  },
  ...
}

⚠️ Important Notes:

Payment methods saved with a customer.id are linked to that customer profile and can be managed through customer-based operations
Payment methods saved without a customer.id remain permanently unassociated and can only be referenced by their token
Best practice: Always include customer.id when saving cards to enable better customer management and payment method organization

💳 Paying with Saved Cards¶

Once a card has been saved, you can use it for future transactions without requiring the customer to re-enter their card details.

Requirements¶

To pay with a saved card, you need:

The payment method ID (token) from the original transaction response
The CVV (encrypted) - may be required depending on Payment Provider support

Request Example¶

{
  "reference": "ORDER-789012",
  "terminal_id": "TERM001",
  "description": "Subscription renewal",
  "currency": "EUR",
  "amount": 5000,
  "transaction_type": "PURCHASE",
  "payment_method": {
    "type": "saved_card",
    "data": {
      "payment_method_id": "abc123def456ghi789",
      "encrypted_cvv": "base64_encrypted_value"
    }
  },
  "customer": {
    "id": "CUST123456",
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com"
  },
  "browser_info": {
    "user_agent": "Mozilla/5.0...",
    "accept_header": "text/html,application/xhtml+xml...",
    "java_enabled": false,
    "color_depth": 24,
    "screen_height": 1080,
    "screen_width": 1920,
    "time_zone_offset": -120,
    "language": "en-US"
  },
  "metadata": {},
  "return_url": "https://merchant.example.com/return",
  "error_url": "https://merchant.example.com/error",
  "cancel_url": "https://merchant.example.com/cancel"
}

Key Differences for Saved Card Payments¶

Field	Value	Description
`payment_method.type`	`"saved_card"`	Indicates using a saved payment method
`payment_method.data.payment_method_id`	`string`	The token from the original save operation
`payment_method.data.encrypted_cvv`	`string`	Base64-encoded encrypted CVV

⚠️ Security Note:

CVV may be required for saved card transactions depending on Payment Provider support
When required, CVV must be encrypted using your merchant public key
The full card number is never required for saved card payments
Only the payment method ID (and CVV if required) are needed

Response Example¶

{
  "result": {
    "id": "TXN789012",
    "status": "APPROVED",
    "payment_method": {
      "method": "411111-******-1111",
      "type": "saved_card",
      "brand": "VISA",
      "masked": "411111-******-1111",
      "token": "abc123def456ghi789"
    },
    "approved": true,
    ...
  }
}

⚠️ Error Handling¶

Tokenization Not Enabled¶

If tokenization is not enabled at the merchant level:

{
  "status": "INVALID",
  "errors": [
    {
      "property": "tokenization",
      "message": "one of requested features not supported=[TOKENIZATION]"
    }
  ]
}

Solution: Contact your payment platform administrator to enable tokenization.

Customer Not Found¶

If you provide a customer.id that doesn't exist:

{
  "status": "INVALID",
  "errors": [
    {
      "property": "customer.id",
      "message": "Customer with id 'CUST123456' not found"
    }
  ]
}

Solution: Create the customer first, or omit customer.id to save the payment method without customer association.

Invalid Payment Method ID¶

If the payment method ID is invalid or doesn't exist:

{
  "status": "INVALID",
  "errors": [
    {
      "property": "payment_method.data.payment_method_id",
      "message": "Payment method not found"
    }
  ]
}

Solution: Verify the payment method ID is correct and that the payment method hasn't been deleted.

📋 Complete Workflow Examples¶

Workflow 1: First-Time Payment with Card Saving¶

Encrypt card data using merchant public key
Submit transaction with tokenization.save_card_for_future_payments: true
Store payment method ID from response for future use
Use saved card for subsequent payments

Workflow 2: Subscription Payment with Saved Card¶

Retrieve payment method ID from your database (saved from first transaction)
Encrypt CVV (collected from customer)
Submit transaction with payment_method.type: "saved_card"
Process response as normal transaction

Card Authorization API Reference - Detailed API specification
Network Token Reference - Network token payment method details
Encryption Example - How to encrypt card data

✅ Best Practices¶

Always encrypt sensitive data: Card numbers, CVV, and expiration dates must be encrypted
Use customer IDs: Always associate saved cards with a customer ID for better organization
Handle tokens securely: Store payment method IDs securely in your database
Implement webhooks: Use webhooks for reliable payment status updates
Validate responses: Always check the status and approved fields in responses
Error handling: Implement comprehensive error handling for all API calls
Compliance: Ensure your integration meets PCI-DSS and local regulatory requirements

API Integration¶

🔐 Authentication¶

HTTP Headers¶

Obtaining an Access Token¶

💳 Processing Card Payments¶

Endpoint¶

Data Encryption¶

Basic Request Example¶

Network Token Payments (Apple Pay / Google Pay)¶

Data Encryption¶

Request Example (Apple Pay)¶

Request Example (Google Pay — PAN_ONLY)¶

Network Token Payment Data Fields¶

💾 Saving Cards for Future Payments¶

Requirements for Card Tokenization¶

Saving a Card During Payment¶

Tokenization Parameters¶

Response with Saved Payment Method¶

🔑 Assigning Saved Payment Methods to a Customer¶

With customer.id (Recommended)¶

Without customer.id¶

💳 Paying with Saved Cards¶

Requirements¶

Request Example¶

Key Differences for Saved Card Payments¶

Response Example¶

⚠️ Error Handling¶

Tokenization Not Enabled¶

Customer Not Found¶

Invalid Payment Method ID¶

📋 Complete Workflow Examples¶

Workflow 1: First-Time Payment with Card Saving¶

Workflow 2: Subscription Payment with Saved Card¶

🔗 Related Documentation¶

✅ Best Practices¶

With `customer.id` (Recommended)¶

Without `customer.id`¶