The NumeroPay API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can acces the api from any applicatiuon to create Payment Transactions and get updates for created transaction.

1https://api.numeropay.com

Authentication

NumeroPay API uses Bearer authentication (also called token authentication) as HTTP authentication scheme.

Token passed for authentication is a JWT token. For Merchant integration, the JWT token is signed using Merchant’s secrets (not user’s secrets).

To obtain the merchant secrets, please look into Merhcant Panel > Settings > Your Mercahnt Account > API Secrets. These secrets are generated on a Merchant level.

1GET /transaction/<<Your transaction Id>>
2Host: api.numeropay.com
3Authorization: Bearer <<your token here>>

Generating Auth JWT Token

To generate the JWT token, you need to follow the following steps:

1. Create a token payload with following schema :
   JWT Token Body

   JSON

   1{
   2    "scopes": [
   3      "YOUR",
   4      "SCOPES"
   5    ],
   6    "iat": 1602501211,
   7    "exp": 1602502411,
   8    "iss": "merchant.numeropay",
   9    "sub": "MERCHANT ID"
   10  }

2. Use following header and Update you KEY_ID
   JWT Token Header

   JSON

   1{
   2    "alg": "HS256",
   3    "type": "JWT",
   4    "keyid": "KEY_ID"
   5  }

3. Generate signature
   Generating JWT Signature

   JAVASCRIPT

   1const SignaturePayload = base64UrlEncode(header) + "." + base64UrlEncode(payload);
   2HMACSHA256(SignaturePayload, KEY_SECRET);

See example JWT token.

JWT Token Fields

Below is a table for fileds used int JWT tokens explained in detail.

For JWT Header

API Request

NumeroPay API request should always accompany the Authorization header. For POST requests, the data has to be passed as a JSON object with content type set to application/json.

1curl --location --request POST 'https://api.numeropay.com/transaction' \
2  --header 'accept: application/json, text/plain, */*' \
3  --header 'content-type: application/json;charset=UTF-8' \
4  --header 'Authorization: Bearer <<YOUR JWT TOKEN>>' \
5  --data-raw '{"amount":100,"busin ... nsaction"}'

The Response for the above request return a transaction object in reponse wrapper.

1{
2  "data": {
3    "id": "5CD0RGCKJ",
4    "merchant": "17c69865-7edd-4d05-bc70-65a1b85b9322",
5    "businessName": "Infinity Group",
6    "channel": 1,
7    "amount": 100,
8    "currency": "aud",
9    "description": "sample transaction",
10    "structure": {},
11    "state": 0,
12    "createdOn": "2020-10-14T02:31:23.328Z",
13    "updatedOn": "2020-10-14T02:31:23.328Z",
14    "ipAddress": "120.19.86.103"
15  },
16  "success": true
17}

API Response

All the success API calls follow a standard response format. A success response consits of two properties explained below:

In case of errors, Error Response is returned with any of the error mentioned in API Response Errors and sucess always set to false.

1{
2  "success": false,
3  "error": {
4    "code": 403,
5    "message": "Action not allowed",
6    "name": "FORBIDDEN"
7  }
8}

API Response Errors

In case of an error response, the flowing is the list of errors which will return as response.

Payments API

Payments API will allow you to access manage transactions in your merchant account in NumeroPay. You can create new transaction and get updated state of the transaction.

All Payment Api calls are made on /transaction resource. Below is the list of awailable api calls on transaction resource:

1. Create new transaction - POST /transaction
2. Get transaction update - GET /transaction/TRANSACTION ID

Create new Transaction

To create new transaction, you need to call POST /transaction with JSON body with your transaction details.

Properties of the JSON Request Body are explined below:

Returns

When successful, this call returns the generated transaction object (See Payment Schema).

Get All Transactions

To get a paginated and filtered list of your transaction you need to call GET /transaction. The transactions in this api call is limmited top the mertchant mentioned in the JWT token.

For pagintation, below is the list of query paramerters:

For filters, below is the list of query paramerters:

Returns

When successful, this call returns an array of transaction object (See Payment Schema) paginated and filterd based on query parameters.

Get Transaction Update

To get an existing transaction object, you need to call GET /transaction/<<TRANSACTION ID>>.

Returns

When successful, this call returns the transaction object (See Payment Schema) for the passed Transaction ID.