General concepts¶
Learn our general concepts and principles all our APIs has common.
Security¶
Every API request is secured with auth token
, which is transported in HTTP authorization header (Authorization: Bearer <token>).
To generate auth token use POST /auth-tokens-by-action
API.
Prerequisites for generating auth token are:
merchantCode
- This code is obtained during the merchant Merchant enrollment process as your Merchant ID.secret
- This is Merchant Secret key obtained upon merchant Merchant enrollment process. This must be kept secure and cannot be shared in publicly accessible areas such as GitHub, client-side code, and so forth.
Auth token can carry various privileges and when limited to a specific payment id, it can be shared with client side code such as web applications.
Auth token uses JWT so it can be easily decoded to verify its content by pasting the token on the mentioned page.
Basic usage¶
The POST /auth-tokens-by-action
endpoint accepts action
and idPayment
attributes to restrict the privileges of the token holder.
Optionally money
attribute can be used to create a token for payment limited only to specified amount and currency.
Here is an example of generating an auth token for creating payment with platform web application:
curl -X POST 'https://api.sandbox.aopay.io/auth-tokens-by-action' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-API-Version: 2' \
-d '{
"merchantCode": "YOUR_MERCHANT_ID",
"secret": "YOUR_MERCHANT_SECRET_KEY",
"validitySecs": 600,
"action": "PAYIN_CREATE",
"idPayment": "TST-112233",
"money": {
"currencyCode": "INR",
"amount": 5000
}
}'
The generated token can be used to create payin with the specified id TST-112233
by allowing these endpoints:
POST /payins/!availablePaymentOptions
for ability to the choose payment method / operator by userPOST /payins/TST-112233
for the ability to create specific payment with Merchant Order ID TST-112233GET /payins/TST-112233
for the ability to get payment (but only with Merchant Order ID TST-112233) details/status
Each auth token can be generated only for desired operation. The previous example can be reduced only to:
curl -X POST 'https://api.sandbox.|TenantDomain|/auth-tokens-by-action' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-API-Version: 2' \
-d '{
"merchantCode": "YOUR_MERCHANT_ID",
"secret": "YOUR_MERCHANT_SECRET_KEY",
"validitySecs": 600,
"action": "PAYIN_INFO",
"idPayment": "TST-112233",
}'
With this auth token only detail of incoming payment with Merchant Order ID TST-112233 can be obtained, it is safe to share this token in client side code, emails, etc.
Fine-grained privileges¶
If the above endpoint does not provide enough granularity, you can limit the access to specific URLs using POST /auth-tokens
endpoint.
It accepts operations
attribute with URL list. Optionally money
attribute can be used to create a token for payment limited only to specified amount and currency.
Values passed in operations
are simply HTTP methods followed by an endpoint to which permission should be granted.
Here is an example of generating an auth token for creating payment with platform web application:
curl -X POST 'https://api.sandbox.aopay.io/auth-tokens' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-API-Version: 2' \
-d '{
"merchantCode": "YOUR_MERCHANT_ID",
"secret": "YOUR_MERCHANT_SECRET_KEY",
"validitySecs": 600,
"operations": [
"POST /payins/!availablePaymentOptions",
"POST /payins/TST-112233",
"GET /payins/TST-112233"
],
"money": {
"currencyCode": "INR",
"amount": 5000
}
}'
There are 3 operations allowed within this token:
POST /payins/!availablePaymentOptions
for ability to the choose payment method / operator by userPOST /payins/TST-112233
for the ability to create specific payment with Merchant Order ID TST-112233GET /payins/TST-112233
for the ability to get payment (but only with Merchant Order ID TST-112233) details/status
Each auth token can be generated only for desired operation. The previous example can be reduced only to:
curl -X POST 'https://api.sandbox.aopay.io/auth-tokens' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-API-Version: 2' \
-d '{
"merchantCode": "YOUR_MERCHANT_ID",
"secret": "YOUR_MERCHANT_SECRET_KEY",
"validitySecs": 600,
"operations": [
"GET /payins/TST-112233"
]
}'
With this auth token only detail of incoming payment with Merchant Order ID TST-112233 can be obtained, it is safe to share this token in client side code, emails, etc.
General privileges¶
As the operations
format supports regular expressions, a more general token can be created to e.g. access/create multiple payments with a single token.
For example, use POST /payins/.*
operation to be able to create incoming payment with any Merchant Order ID or GET /payins/.*
to access any incoming payment details/status.
Tokens with general privileges are not intended to be used by client side code, emails, etc, as they are considered serious security risks.
Here is an example of generating token for checking status of all available incoming payments:
curl -X POST 'https://api.sandbox.aopay.io/auth-tokens' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'X-API-Version: 2' \
-d '{
"merchantCode": "YOUR_MERCHANT_ID",
"secret": "YOUR_MERCHANT_SECRET_KEY",
"validitySecs": 600,
"operations": [
"GET /payins/.*"
]
}'
Versioning¶
Latest API version: 2.50
The API version provided in HTTP request controls the API and callbacks behavior you see (e.g., what properties you see in responses, what parameters you’re permitted to send in requests, etc.).
Every request must include HTTP header X-API-Version with only MAJOR version of used API. If no version or unsupported version of API is sent, HTTP 404 Not Found error will be returned. E.g. request for API in version 2.50 must include HTTP header:
X-API-Version: 2
All minor version changes are considered backward compatible (non breaking) changes to the API. With every backward incompatible (breaking) change new major version of API is released. The old version is supported for an announced period of time to enable the seamless upgrading of your system.
Non breaking changes¶
The following changes are considered as backwards compatible (non breaking) changes and thus do not change the major version of API:
Adding new API resources.
Adding new optional request parameters to existing API methods.
Adding new properties to existing API responses. You should ignore unexpected properties.
Changing the order of properties in existing API responses.
Adding new event types. Your callback listener should gracefully handle unfamiliar event types.
Adding new items to code-list endpoints, such as
GET /currencies
,GET /payment-operators
etc.
Request IDs¶
All calls creating new payments
(POST /payins/{idPayin}
, POST /payouts/{idPayout}
) must include
an your Merchant Order ID (idPayin
, idPayout
) provided by your side.
Consider using UUID or another random string with enough entropy to avoid collisions.
APIs for creating new entities supports idempotency to safely retry requests without accidentally performing the operation twice. If no response is received due to disrupted network connection or other reason it is safe to make the same request (with the same ID) again. If the request was already accepted by our platform, then 409 Conflict HTTP error is returned.
Callbacks¶
When a payment request is accepted by platform, a change of status of this transaction is alerted by a callback. Callbacks are anemic events
that only notify about change within a given entity, but do not carry the change itself (mainly for security reasons) so as an after effect of callback
the call of GET /payins/{idPayin}
, GET /payouts/{idPayout}
should follow to check the status.
Examples of how to check payment details are described in the section Payment status check, Payment status check.
Query for multiple values¶
If you need to use multiple values for attributes in query operations use comma (,
) as the separator of these the values.
If one of values is unsupported/invalid, this value is ignored.
E.g. for GET /balances
for currency IDR and INR make the query as: /balances/?currencies=INR,IDR
.
Throttling¶
There is a limitation of how many request can be processed with our platform. You can make up to 10 requests per second. If this limitation is exceeded 429 Too many requests HTTP error is returned and request is not processed.