Skip to content

Axepta Online API (2.0.0)

The Axepta Online API allows you to seamlessly process and manage payments, supporting 350+ payment methods worldwide. Built on REST principles, the API is designed to be predictable and developer-friendly, with resource-oriented URLs, JSON-encoded requests and responses, and standard HTTP status codes.

Security

The Axepta Online API is designed with maximum security while remaining easy to implement. All communication occurs over HTTPS (TLS 1.2 or higher), ensuring end-to-end encryption at the transport level. This prevents packet sniffing, replay attacks, and other vulnerabilities without requiring additional encryption of the data itself.

Test Before You Go Live

Use our test environment to test your integration without affecting live data. The root URL determines whether the request is for test or live integration.

Download OpenAPI description
index.json
index.yaml
Languages
Servers
Test server

https://test.paymentpage.axepta.bnpparibas/api/v2/

Production server

https://paymentpage.axepta.bnpparibas/api/v2/

Guide

For functional documentation, please refer to the Confluence Guide

Authentication

Securely authenticate API requests using Basic Auth or OAuth 2.0

The Axepta Online API supports two authentication methods to ensure secure access to payment processing and management endpoints. Choose the approach that aligns with your integration needs:

Basic Authentication

Use your Merchant ID as the username and API Key as the password. Combine them in the format MerchantID:APIKey, encode the string using Base64, and include it in the Authorization header with the Basic prefix for direct access to endpoints.

OAuth 2.0

Generate a short-lived JSON Web token (JWT) by authenticating with your API key via the authorization/oauth/token endpoint.

Operations

Payments

Create checkout session

This endpoint generates a URL for a hosted payment page where customers can securely select their preferred payment method and complete their transaction.

Create payment

This endpoint is used to initiate a payment for a specific payment method. You can choose between two integration types:

  • HOSTED: Returns a URL for a payment method-specific hosted form, where the customer is redirected to securely complete the payment.
  • DIRECT: Enables server-to-server communication, where you manage the payment UI and directly interacts with the API to process payments.

Note that not all payment methods support both HOSTED and DIRECT integration types. Some support only one of these options, while others support both. For detailed information about the supported integration types for each payment method, refer to the payment method-specific documentation in our product guide.

Confirm payment

This endpoint is used for payment methods that require a multi-step payment flow. It allows you to confirm a previously created payment instance (initiated via the Create Payment endpoint) to complete the transaction. This step is essential for certain payment methods to finalize the payment process.

Incremental authorization

This endpoint allows you to increase the authorized amount for an existing card transaction when the initial authorization is insufficient. The additional amount is appended to the original authorization, and the total authorized amount reflects both.

Reverse payment

This endpoint is used to reverse a payment that has not yet been captured, effectively canceling the authorization.

Capture payment

This endpoint is used to capture an existing authorized payment.

Refund payment

This endpoint is used to refund a captured payment.

Refund payment without reference

This endpoint is used to refund a payment without reference.

Retrieve payment details by Payment ID

This endpoint is used to retrieve payment details with the Payment ID (payId)

Retrieve payment details by Transaction ID

This endpoint is used to retrieve payment details with the Transaction ID (transId)

Update payment details

This endpoint is used to update payment details

Create payment link

This endpoint allows you to generate a payment link that can be shared with customers via email, SMS, or other channels. When customers click the link, they are redirected to a hosted payment page where they can select their preferred payment method and complete the transaction.

Operations

Customers

Retrieve customers

This endpoint is used to retrieve a list of customers.

Retrieve customer

This endpoint is used to retrieve details of a specific customer.

Update customer data

This endpoint is used to update customer data.

Delete customer

This endpoint is used to delete a specific customer and associated payment methods.

Retrieve payment methods

This endpoint is used to retrieve all payment methods for a specific customer.

Retrieve payment method

This endpoint is used to retrieve details of a specific payment method.

Delete payment method

This endpoint is used to delete a specific payment method.

Operations

Get list of customers

Request

Get list of customers

Security
bearerAuth or basicAuth
Query
pagenumber(int)required

Specifies page number

Example: page=2
createdFromstring(date)

The createdAt date from witch the customers will be fetched

Example: createdFrom=2025-05-12
createdTostring(date)

The createdAt date to witch the customers will be fetched

Example: createdTo=2025-05-15
merchantCustomerIdstring

The merchant customer id

Example: merchantCustomerId=Test_Merchant
emailstring

The email address

Example: email=test@gmail.com
phoneCountrystring

The phone country code

Example: phoneCountry=33
phoneNumberstring

The phone number

Example: phoneNumber=98746321
curl -i -X GET \
  'https://test.paymentpage.axepta.bnpparibas/api/v2/customers?page=2&createdFrom=2025-05-12&createdTo=2025-05-15&merchantCustomerId=Test_Merchant&email=test%40gmail.com&phoneCountry=33&phoneNumber=98746321' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Customers successfully retrieved

Bodyapplication/json
totalNumberOfPagesnumber

Indicates total number of pages that exist.

totalNumberOfItemsnumber

Indicates total number of items that exist.

pagenumber

Indicates number of page that is retrieved.

pageSizenumber

Indicates max number of items on page.

dataArray of objects(customerDetailsResponse)
Response
application/json
{
  "totalNumberOfPages": 5,
  "totalNumberOfItems": 82,
  "page": 5,
  "pageSize": 20,
  "data": [
    { … },
    { … }
  ]
}

Get customer details

Request

Get customer details

Security
bearerAuth or basicAuth
Path
idstringrequired

Customer Id

Example: cu_841b9b1a99fc4f0
curl -i -X GET \
  https://test.paymentpage.axepta.bnpparibas/api/v2/customers/cu_841b9b1a99fc4f0 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Customer successfully retrieved

Bodyapplication/json
idstring

Unique identifier of the customer assigned by Axepta Online.

merchantCustomerIdstring

Unique identifier of the customer assigned by merchant.

firstNamestring

First name of the customer. Present if passed by merchant in Payment.

lastNamestring

Last name of the customer. Present if passed by merchant in Payment.

companyNamestring

Last name of the customer. Present if passed by merchant in Payment.

emailstring

E-mail address of the customer. Present if passed by merchant in Payment.

phoneobject
scopestring

Scope of customer vault. Present if configured for the merchant in MAT.

createdAtstring(date-time)

Creation date and time in ISO 8601 format.

updatedAtstring(date-time)

Update date and time in ISO 8601 format.

billingAddressobject
lastUsedAtstring(date-time)

Last used date and time in ISO 8601 format.

Response
application/json
{
  "id": "cu_841b9b1a99fc4f0",
  "merchantCustomerId": "1234567890",
  "firstName": "Max",
  "lastName": "Mustermann",
  "email": "maxmustermann@example.com",
  "phone": {
    "countryCode": "33",
    "number": "234567890"
  },
  "billingAddress": {
    "streetName": "Marienplatz 11A",
    "city": "Munich",
    "postalCode": "883433",
    "state": "Bavaria",
    "country": "deu"
  },
  "scope": "demo_parent",
  "createdAt": "2023-12-21T12:10:58.087",
  "updatedAt": "2024-10-01T12:10:58.087",
  "lastUsedAt": "2024-10-15T12:10:58.087"
}

Update customer details

Request

Updates details about customer

Security
bearerAuth or basicAuth
Path
idstringrequired

Customer Id

Example: cu_841b9b1a99fc4f0
Bodyapplication/json
firstNamestring

First name of the customer. Must be present if companyName is not present.

lastNamestring

Last name of the customer. Must be present if companyName is not present.

companyNamestring

Company name of the customer. Must be present if firstName and lastName are not present.

emailstring

E-mail address of the customer.

phoneobject
billingAddressobject
curl -i -X PATCH \
  https://test.paymentpage.axepta.bnpparibas/api/v2/customers/cu_841b9b1a99fc4f0 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "firstName": "Jane",
    "lastName": "Doe",
    "email": "janedoe@example.com",
    "phone": {
      "countryCode": "33",
      "number": "234567889"
    },
    "billingAddress": {
      "streetName": "Marienplatz 55B",
      "city": "Munich",
      "postalCode": "883433",
      "state": "Bavaria",
      "country": "deu"
    }
  }'

Responses

Customer successfully updated

Bodyapplication/json
idstring

Unique identifier of the customer assigned by Axepta Online.

merchantCustomerIdstring

Unique identifier of the customer assigned by merchant.

firstNamestring

First name of the customer. Present if passed by merchant in Payment.

lastNamestring

Last name of the customer. Present if passed by merchant in Payment.

companyNamestring

Last name of the customer. Present if passed by merchant in Payment.

emailstring

E-mail address of the customer. Present if passed by merchant in Payment.

phoneobject
scopestring

Scope of customer vault. Present if configured for the merchant in MAT.

createdAtstring(date-time)

Creation date and time in ISO 8601 format.

updatedAtstring(date-time)

Update date and time in ISO 8601 format.

billingAddressobject
lastUsedAtstring(date-time)

Last used date and time in ISO 8601 format.

Response
application/json
{
  "id": "cu_841b9b1a99fc4f0",
  "merchantCustomerId": "1234567890",
  "firstName": "Max",
  "lastName": "Mustermann",
  "email": "maxmustermann@example.com",
  "phone": {
    "countryCode": "33",
    "number": "234567890"
  },
  "billingAddress": {
    "streetName": "Marienplatz 11A",
    "city": "Munich",
    "postalCode": "883433",
    "state": "Bavaria",
    "country": "deu"
  },
  "scope": "demo_parent",
  "createdAt": "2023-12-21T12:10:58.087",
  "updatedAt": "2024-10-01T12:10:58.087",
  "lastUsedAt": "2024-10-15T12:10:58.087"
}

Delete customer details

Request

Delete customer details

Security
bearerAuth or basicAuth
Path
idstringrequired

Customer Id

Example: cu_841b9b1a99fc4f0
curl -i -X DELETE \
  https://test.paymentpage.axepta.bnpparibas/api/v2/customers/cu_841b9b1a99fc4f0 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Customer successfully deleted

Bodyapplication/json
idstring

Unique identifier of the customer assigned by Axepta Online.

deletedboolean

Indicates if the payment method record was deleted or not.

Response
application/json
{
  "id": "cu_841b9b1a99fc4f0",
  "deleted": true
}

Get list of payment methods for customer

Request

Get list of payment methods for customer

Security
bearerAuth or basicAuth
Path
idstringrequired

Customer Id

Example: cu_841b9b1a99fc4f0
curl -i -X GET \
  https://test.paymentpage.axepta.bnpparibas/api/v2/customers/cu_841b9b1a99fc4f0/paymentMethods \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Payment methods successfully retrieved

Bodyapplication/json
gatewayCustomerIdstring
dataArray of objects(paymentMethodsResponse)
Response
application/json
{
  "gatewayCustomerId": "cu_841b9b1a99fc4f0",
  "data": [
    { … },
    { … }
  ]
}

Get payment method details

Request

Get payment method details

Security
bearerAuth or basicAuth
Path
customerIdstringrequired

Customer Id

Example: cu_96586bedjfe4tg3
paymentMethodIdstringrequired

Payment Method Id

Example: pm_5555b1a99fe4tg3
curl -i -X GET \
  https://test.paymentpage.axepta.bnpparibas/api/v2/customers/cu_96586bedjfe4tg3/paymentMethods/pm_5555b1a99fe4tg3 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Payment Method successfully retrieved

Bodyapplication/json
idstring

Unique ID assigned by Axepta Online for the payment method record.

typestring

Determines type of payment method. CARDS, SEPA_DD. For now only CARDS is in scope.

last4Digitsstring
pseudoCardNumberstring
cardHolderNamestring
brandstring
expiryDatestring
createdAtstring(date-time)

Creation date and time in ISO 8601 format.

updatedAtstring(date-time)

Update date and time in ISO 8601 format.

lastUsedAtstring(date-time)

Last used date and time in ISO 8601 format.

Response
application/json
{
  "id": "pm_5555b1a99fe4tg3",
  "type": "card",
  "last4Digits": "4242",
  "pseudoCardNumber": "0132332232424242",
  "cardHolderName": "Max Mustermann",
  "brand": "visa",
  "expiryDate": "202506",
  "createdAt": "2023-12-21T12:10:58.087",
  "updatedAt": "2024-10-01T12:10:58.087",
  "lastUsedAt": "2024-10-15T12:10:58.087"
}

Delete payment method details

Request

Delete payment method details

Security
bearerAuth or basicAuth
Path
customerIdstringrequired

Customer Id

Example: cu_96586bedjfe4tg3
paymentMethodIdstringrequired

Payment Method Id

Example: pm_5555b1a99fe4tg3
curl -i -X DELETE \
  https://test.paymentpage.axepta.bnpparibas/api/v2/customers/cu_96586bedjfe4tg3/paymentMethods/pm_5555b1a99fe4tg3 \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Payment Method successfully deleted

Bodyapplication/json
idstring

Unique ID assigned by Axepta Online for the payment method record.

deletedboolean

Indicates if the payment method record was deleted or not.

Response
application/json
{
  "id": "pm_5555b1a99fe4tg3",
  "deleted": true
}