Welcome to the Getting Started guide for the BankAxept Epayment Platform (EPP).

This text is intended to give both clear descriptions and guidance for integrators and consumers of EPP. It includes an overview of all critical features as well as some general hints of how to utilize this platform.

Introduction

EPaymentPlatform (EPP) is a Payment API for integrators (Integrator) utilizing BankAxept online payments. It is based on a core principle of asynchronous exchange of information where the transactions created can be identified using an EPP defined PaymentId and an integrator defined CorrelationId.
Requests also are idempotent on an Integrator defined MessageId as seen in our MessageId section. Subsequent transaction operations (Capture, Refund etc.) can thereafter be performed as seen according to the Payments Request component part our API spec.

Setting up your EPP integration

In order to set up your EPP integration and start requesting payments, the following operations need to be performed.

Through your BankAxept contact point you should retrieve your unique identifier (ClientId) as an integrator.
Provide a list of IPs that you will be operating from, enabling us to append them to our Allow List. Any additional IPs need to be transmitted to the BankAxept ePayment team contact before being utilized.
Provide a callback URL, which we will utilize as the address prefix for all callbacks.
Provide the certified Authentication Provider which you will use to Authenticate payments.
For network token enrolment, provide the public certificate for the private key that will sign NetworkTokenEnrolmentData. You may also provide an RSA public key wallet encryption certificate, which EPP uses to encrypt the encryptedAccountNumber field in a successful enrolment callback.
Create a bCrypt based hash of a secret of your choice. We recommend reading up on bCrypt to understand the mechanisms involved.
Send the list of IPs, callback URL, bCrypt hash, and, when applicable, public signing and wallet public encryption certificates to your BankAxept ePayment team contact.
Receive EPP's Public Certificate for encryption of sensitive data.
Generate an access token as described in the Authorization section
Utilize the access token to perform payments as described in the Creating a Payment section

Authorization

Once the set-up steps are performed you can then integrate with the Client Authorization Service. The request should contain the secret used to generate the bCrypt based hash as well as your ClientId. This should be sent as a Basic Authentication The resulting access token has a 1-hour lifetime. We recommend refreshing it 5 minutes before end of life. The resulting access_token can then be used to authorize towards all other endpoints by putting it in the Authorization header as Bearer token.

bCrypt guidelines

We recommend using Spring for up to date bCrypt generation. For example the following command will result in a satisfactory bCrypt hash.

# brew tap spring-io/tap && brew install spring-boot
spring encodepassword -a bcrypt <secret>

Authentication provider and Wallet provider flow and interoperation

Please see our Authentication Provider setup and guidelines

End to end setup of profile diagram

sequenceDiagram actor IntegratorRepresentative actor ePaymentRepresentative participant Integrator participant ePaymentPlatform Integrator ->> Integrator: Create bCrypt hash from self defined secret. Integrator ->> IntegratorRepresentative: Transmit resulting bCrypt hash. IntegratorRepresentative ->> ePaymentRepresentative: Transmit resulting bCrypt hash. IntegratorRepresentative ->> ePaymentRepresentative: Provide set of IPs, Authentication Provider, callback URL,<br/>and public signing certificate when applicable. ePaymentPlatform ->> ePaymentPlatform: create ClientId identifying the Integrator. ePaymentRepresentative ->> ePaymentPlatform: Configure Allow List IPs, Authentication Provider, bCrypt hash and callback URL. ePaymentRepresentative -->> IntegratorRepresentative: Send EPP public certificates, ISS value, <br/> Merchant Name, Token Requestor ID, and the AuthenticationProvider-ISS field <br/> and ClientId. Note over IntegratorRepresentative, ePaymentRepresentative: Manual setup completed. Integrator ->> ePaymentPlatform: Generate access token. ePaymentPlatform ->> ePaymentPlatform: Verify request. Note right of ePaymentPlatform: Matching ClientId and performing <br/> a bCrypt hash on the secret. ePaymentPlatform -->> Integrator: Return Access token.

Checklist for information exchange

Information item(s)	Required	Description
ClientId	Yes	Generated by the ePayment Platform and returned to Integrator
Callback URL	Yes	Defined by Integrator, will be the prefix address all Callback requests are sent. Peruse our Callback section for more context.
ClientSecret	Yes	A bCrypt secret that is kept secret at the Integrator and used to generate access tokens.
ClientSecret bCrypt Hash	Yes	A bCrypt secret hash that is sent to the ePaymentPlatform and configured to the Integrators clientID
Authentication Provider	Yes	Inform the EPP team which Authentication Provider you will be utilizing. The ID from this setup must be used in the Authentication of Enrolment and Payment.
ISS	Yes	Once your profile is set up, you will receive the Issuer ID for your Integrator or Authentication Provider profile.
EPP public certificates	Yes	Is sent by EPP during setup, 1. needed to encrypt parts of requests and 2. MTLS verification of callbacks.
Merchant public signing certificate	No	Required only when using Merchant Initiated Transactions. The merchant sends this certificate to EPP for verification of `signedPaymentData`.
Wallet public signing certificate	No	Required only when using network token enrolment. The integrator sends this certificate to EPP for verification of `signedNetworkTokenEnrolmentData`.
Wallet public encryption certificate	No	When provided, EPP encrypts and returns `encryptedAccountNumber` in successful account number and network token enrolment callbacks.
Merchant Name	Yes	Is sent by EPP during setup and must be used as `merchantName` in enrolment permission statements.
Token Requestor ID	Yes	Is sent by EPP during setup and must be used as the encryption issuer.
MerchantId (optional)	No	Depending on your setup you might be issued a new MerchantId as part of your registration or you might.

API entity overview.

Depending on your setup and your business domain you make have any or all of the following entities in the EPP system:

Information item(s)	Description
Authentication Provider	Generated by the ePayment Platform and returned to Integrator
Token Requestor	ClientId_1 defined by integrator.
Payment Initator/Merchant/Super Merchant	ClientId_2 defined by integrator.

Integration guidelines

This section contains general guidelines for integrating with the EPP.

Correlation ID

All requests support an X-Correlation-Id header which can be used to correlate requests and responses. This is especially useful if you always ensure to set this header to a unique value for each request. The X-Correlation-Id is returned in the corresponding callback, allowing you an additional mechanism to correlate the callback with the original request. It is required to use this header for enabling traceability and support.

MessageId

The system acts idempotent on any messageId. It is required that you use a robust uniqueness mechanism (For example UUIDv4 or similar mechanism) to ensure that each request has a unique messageId.

MessageId uniqueness & Callbacks

EPP creates a UUID that is used as a messageId for each callback that is used to distinguish between different requests. This messageId is considered to be part of the message exchange between EEP and the Integrator. This means that the EPP requires you to act idempotent on the messageId in the callback. This is to ensure that you do not perform the same operation multiple times.

Authentication of callbacks

In order to authenticate the callbacks you receive from EPP we enforce Mutual TLS. Both in Test and Production environments. This may be done by utilizing the public certificate provided by EPP during setup.

As an integrator you must support HTTP/1.1

Asynchronous retry policy

Any Asynchronous Requests will be retried if the Response from the Integrator is anything other than 2xx or 4xx. In the case of a 4xx the response will be interpreted as a final state and not retried.

Retries will be performed first after 10 seconds, and thereafter with an exponential backoff for 24 hours. After 24 hours the retry attempts will stop.

The backoff will extend additionally at a rate of 1.5^X seconds where X is the number of retries until a max retry interval of 10 minutes is reached.

Timeouts and expected response times

These data points are intended to give the Integrator an idea of expected behavior to optimize based on their own use case. We expect the Integrator to know their own applications and user behavior best and therefore do not give any strict guidelines on how to handle timeouts.

Please note that the following guidelines are based on the assumption that there are no network issues or other external factors that might affect the response time. Nor does it estimate any additional network time outside of EPP.

For payments the expected resolution time is 50-300 ms.
For payments, if we have not reached a resolution within 6.6 seconds we will return a AuthorisationFailed callback. We will then perform a technical reversal immediately on the payment in question.
The outbound callback request is expected to leave EPP within 1000 ms of the synchronous request resolving.
EPP times out waiting for a callback response after 10 seconds.
An enrollment request times out within 1 hour. If the request has not been resolved within this time frame the request will be considered failed and a callback will be sent to the Integrator.