Payment API (2.0.0)

As a valued client of Paxum , you able to leverage our Payment API to streamline and automate your payment processes. This API is specifically designed to enhance your business efficiency, significantly reducing costs and minimizing the risk of manual errors.

With the Paxum Payment API, you can effortlessly manage a multitude of payment activities. From overseeing account details to processing various types of payments and handling diverse payout methods, all these functionalities are available without the need for manual intervention in the web interface.

For detailed information on specific endpoints and operations of this API, feel free to explore the menu on the left.

The Paxum Payment API prioritizes the security of your financial transactions. To authenticate each API request, it's essential to sign them using your assigned API Access Key and API Secret Key. This signature process is not only crucial for verifying your identity with Paxum but also serves as a protective measure against unauthorized access.

We've designed this authentication mechanism to be compatible with a wide array of major programming languages (PHP/JS/Ruby), ensuring you can integrate it smoothly into various technological environments. This flexibility allows you to seamlessly incorporate Paxum's Payment API into your existing infrastructure.

To assist you in this process, we provide a step-by-step example demonstrating how to correctly sign and send a payload. This example, employing commonly used Linux command-line tools like echo, openssl, and curl, is aimed at illustrating an effective method for secure API request authentication.

Example 1

 $ echo -n "/v2/account/590900/transactions?limit=3" | openssl dgst -sha256 -hmac "iFK7L5K06KBlcIRUespQxRCtcxolknTGdHG0e4O31eM="
 (stdin)= aa6ecd0b6f5c3f90763a4c068a6d991ddb24f8e667411437761ed81c72da57b8

curl --request GET \
    --header 'X-API-KEY: cbKISWlVIoO4xh0SH4noSFrmmY6uwIlqr97IwViMgAo=' \
    --header 'X-API-SIGNATURE: aa6ecd0b6f5c3f90763a4c068a6d991ddb24f8e667411437761ed81c72da57b8' \
    --url 'https://api.paxum.com/v2/account/590900/transactions?limit=3'

Example 2

 $ echo -n '/v2/account/590900/transfer/p2p{"beneficiaryEmail": "test@example.com","amount": 1,"currency": "USD","description": "Service payment"}' | openssl dgst -sha256 -hmac "iFK7L5K06KBlcIRUespQxRCtcxolknTGdHG0e4O31eM="
 (stdin)= dc7d91c82ab1858dea3d7facc76edb4bf54608d9926f0fbc6bf48b754915c7a5

curl --request POST \
    --header 'Content-Type: application/json' \
    --header 'X-API-KEY: cbKISWlVIoO4xh0SH4noSFrmmY6uwIlqr97IwViMgAo=' \
    --header 'X-API-SIGNATURE: 95bae3952f8e820c5eac9f99958f9af5af8e31cc9e6c746d4899a143b2cabb4a' \
    --url 'https://api.paxum.com/v2/account/590900/transfer/p2p' \
    --data '{"beneficiaryEmail": "test@example.com","amount": 1,"currency": "USD","description": "Service payment"}'

To efficiently navigate through large sets of results, the Paxum Payment API implements a pagination technique known as cursoring. This method divides the results into manageable pages, the size of which can be controlled by the limit parameter in your request. Cursoring provides an intuitive way to traverse these pages both forward and backward.

When you make a cursored request, the API response will include several key cursor-related elements: meta.cursor.next, meta.cursor.prev, meta.cursor.current, and meta.cursor.count. These elements are essential for seamless pagination:

• meta.cursor.next: Use this value as the cursor parameter in your next request to obtain the subsequent batch of results.
• meta.cursor.prev: This value, when used as the cursor parameter, fetches the previous batch of results.
• meta.cursor.current: Indicates the current position in the result set.
• meta.cursor.count: Provides the total number of items in the result set.

By effectively using these cursor values, you can precisely and easily navigate through the data provided by the Paxum Payment API.

Example

curl --get \
    --header 'X-API-KEY: <APIKEY>' \
    --header 'X-API-SIGNATURE: <SIGNATURE>' \
    --url 'https://api.paxum.com/v2/account/12345/transactions'
    --data 'limit=3'

{
    "data": [ ... ],
    "meta": {
        "cursor": {
            "count": 3,
            "current": null,
            "next": "NShQHHfwEB1j",
            "prev": null
        }
    }
}

curl --get \
    --header 'X-API-KEY: <APIKEY>' \
    --header 'X-API-SIGNATURE: <SIGNATURE>' \
    --url 'https://api.paxum.com/v2/account/12345/transactions' \
    --data 'limit=3' \
    --data 'cursor=NShQHHfwEB1j'

{
    "data": [ ... ],
    "meta": {
        "cursor": {
            "count": 3,
            "current": "NShQHHfwEB1j",
            "next": "NSSV7ChtxVjG",
            "prev": "ggAYt3ZM3b2e"
        }
    }
}

Paxum Payment API includes asynchronous operations, such as Customer Verification and Payments. Typically, the results of these operations are not available instantly and require subsequent status checks.

Instead of continuously polling for status updates after initiating an asynchronous method, we offer a more efficient solution: webhooks. By configuring a webhook in the Merchant API settings, you can receive real-time notifications about the completion of your request.

When you set up a webhook, the Paxum Payment API will send an HTTP POST notification to your specified endpoint as soon as the request is completed. This approach not only saves resources but also provides timely updates, enhancing the overall efficiency of your asynchronous operations.

The Paxum Payment API signs all webhook events sent to your endpoints with a signature. This feature allows you to verify that the events were sent by Paxum Payment API rather than a third party.

The signature is created using a unique secret key, which is generated for each endpoint separately. We include the signature in the X-SIGNATURE HTTP-header.

Example of Incoming Request

POST / HTTP/1.1
Host: webhook.example.com
Accept: */*
Accept-Encoding: gzip
Content-Length: 176
Content-Type: application/json
X-Signature: 94f797bb7b69ffa426d7fd1285027b38f690bfd4e10ae358d14cf14d27294477

{"requestId":"c26181c6-8e29-42fd-b4e6-ad86e2c92183","status":"COMPLETE","statusCode":"0","statusMessage":null,"payload":{"transactionId":11111111,"status":"VALIDATED","fee":1}}

Signature Verification

echo -n '{"requestId":"c26181c6-8e29-42fd-b4e6-ad86e2c92183","status":"COMPLETE","statusCode":"0","statusMessage":null,"payload":{"transactionId":11111111,"status":"VALIDATED","fee":1}}' | openssl dgst -sha256 -hmac "sRQgK+gJSD4qFsVGct3sYU6kWMnO0OoWLAClzTlz32Y="

(stdin)= 94f797bb7b69ffa426d7fd1285027b38f690bfd4e10ae358d14cf14d27294477

Paxum Payment API Sandbox is an essential tool for testing and ensuring a smooth integration before your production launch. This dedicated environment is designed to mimic the behavior of the live API, using test-specific elements and simulated responses based on mock data. It allows you to safely test the functionality of the Payment APIs in real-time scenarios without affecting live data.

The endpoint for accessing the Paxum Payment API Sandbox is sandbox-api.paxum.com. This separate endpoint ensures that all your test transactions remain isolated from your production environment, providing a secure and accurate testing ground for your integration needs.

Testing Customer Lookup method

Testing Customer Verification method

Testing Payment method

Payment API limits the number of API calls within any given hour. By default maximum API limit in a 1-hour window is 5000 requests. HTTP 429 return code is used when breaking a request rate limit.

The Paxum Payment API supports idempotency for safely retrying requests without accidentally performing the same operation twice.

To perform an idempotent request, simply add the X-Idempotency-Key header to your POST request. The value of X-Idempotency-Key should be a unique identifier for the request, represented as a string not exceeding 64 characters. We recommend using V4 UUID for this purpose.

If you attempt to resend a request with the same X-Idempotency-Key and X-Api-Key combination within 72 hours, the API will ensure that you receive an identical response to that of the original request.

During the validity period, you can only send the same payload with the same idempotency key. If the payload is different, but the idempotency key is the same, you receive an HTTP 409 error