Introduction
Welcome to Payger's Public API version 1.0-RELEASE.
This is an HTTP-based RESTful API and uses OAuth 2.0 for authentication and authorization.
API requests and responses are formatted in JSON.
Features for both Merchants and Wholesalers are available.
Authentication
To authenticate against Payger's Public API, you need a valid OAuth2 access token.
To get this token you will have to provide your Payger API key and secret.
Get a new token
Example Request (Get token):
curl -X POST https://merchants-api.payger.com/api/v1/oauth/token \
-H 'Authorization: Basic dHdvaW1wdWxzZTpTRkRQZzU3YlZKWXliV1px' \
-F grant_type=password \
-F username=<username> \
-F password=<password>
var request = require("request");
var options = { method: 'POST',
url: 'https://merchants-api.payger.com/api/v1/oauth/token',
headers:
{ Authorization: 'Basic dHdvaW1wdWxzZTpTRkRQZzU3YlZKWXliV1px',
'Content-Type': 'application/x-www-form-urlencoded'
},
formData:
{ grant_type: 'password',
username: 'merchant1',
password: 'password1' } };
request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(body);
});
Example response (Get token):
{
"access_token": "eyJhbG...",
"token_type": "bearer",
"refresh_token": "eyJhbG...",
"expires_in": 9999999,
"scope": "read",
"organization": "PAYGER",
"jti": "3a351273-b034-4856-a5a7-749f581c5be8"
}
To create a valid token call the OAuth2 token url:
POST /oauth/token
This resource uses Basic Authentication.
Follow these steps to retrieve an access token:
1) Concatenate your OAuth client name with a colon character ":", (leave the password empty!). Possible values for OAuth client are: "netevia", "payger" and "payger_wc_plugin"
2) Base64 encode the string from 1)
3) Include the resulting encoded string from 2) in an Authorization header as follows
Authorization: Basic <encoded string>
Request parameters
Parameter | Description | Value |
---|---|---|
grant_type |
Type of grant | "password" |
username |
API Key | <API_KEY> |
password |
API Secret | <API_SECRET> |
Alternative
As an alternative you can also pass these attributes as part of the url:
POST /oauth/token?grant_type=password&username=<API_KEY>&password=<API_SECRET>
The Authorization
header is still required.
Refresh an existing token
Refresh tokens are tokens that can be used to replace expired access tokens without providing user credentials. These tokens are also subject to expiration.
Refresh tokens are issued when an access token is requested using Payger API user credentials (additionally, they are issued when requesting a new access token with a refresh token).
When requesting an access token using a refresh token you must use a grant type of refresh_token
and provide the refresh token in the request body.
Request Parameters
Parameter | Description | Value |
---|---|---|
grant_type |
grant type | "refresh_token" |
refresh_token |
refresh token as provided in the previous OAuth requests (New/Refresh) | <REFRESH_TOKEN> |
Using a valid token
Upon successful token retrieval, the token can be used passing it as a Bearer
token in the Authorization
header, in all the calls to the MerchantsAPI endpoints:
Example:
GET https://merchants-api.payger.com/api/v1/merchants/balances/
Request Headers:
Content-Type:"application/json"
Authorization:"Bearer eyJhbG..."
API Details
Urls
Example (API Url):
https://merchants-api.payger.com/api/v1/merchants/balances
All the available urls are in the form https://merchants-api.payger.com/api/stage/resource and tipically the resource name is in the plural form (e.g. balances, payments, fees).
Message format
All the API responses (if mandatory) will return a message using the same json format (envelope).
Each response can contain the following fields:
Field | Description |
---|---|
content Object |
An object with the API response, if any |
error Object |
An object containing error information, if any |
error.message String |
A string with detailed error description |
error.code Number |
The error code number |
timestamp Timestamp |
A timestamp indicating the server time of response |
Also some response headers may be returned, such as:
Header | Description |
---|---|
Content-Type |
The response content type |
Date |
The response server timestamp |
Finally, a relevant HTTP status response code is also returned.
Objects
All the objects the user is allowed to manage contain generic fields such as:
Object | Description |
---|---|
id String |
Object unique identifier |
created Timestamp |
Timestamp when the object was first created |
lastUpdated Timestamp |
Timestamp when the object was last updated |
externalId String |
Object external id (external object identifier - must be unique) |
description String |
Object free text description |
metadata Object |
Object meta info |
Simple Data types
Object | Type | Format |
---|---|---|
Id | String | min length: 3, max length: 45 |
Timestamp | Timestamp | yyyy-MM-dd HH:mm:ss |
Date | String | yyyy-MM-dd |
Number | String Number |
"9999999999.9999999999" 9999999999.9999999999* |
Precision | Byte | |
Currency | String | min length: 3, max length: 45 |
Metadata | Object | min items: 0, max items: 20 |
Complex Data types
QrCode Example:
"qrCode":{
"content":"iVBORw...",
"fileSize":250,
"fileType":"png",
"encoding":"UTF-8",
"created":"2018-04-26 17:24:32"
}
QrCode
Attribute | Type | Format |
---|---|---|
content | String | Encoded bytes |
fileSize | int | Dimensions of the qrCode image (square) |
fileType | String | Image type |
encoding | String | Encoding used to encode the qrCode image to string |
Callback
Attribute | Type | Format |
---|---|---|
url | String | url to be called |
method | String | method used when calling the url (One of POST, PUT, DELETE or GET) |
params | Object | parameters to include on the callback body |
Status codes
The API uses the following status codes:
Code | Type | Meaning |
---|---|---|
200 | Success | OK - Successful request. |
201 | Success | Created - New resource created. |
202 | Success | Accepted - Accepted for processing. |
204 | Success | No content - Successfully processed the request but no content to return. |
400 | Client Error | Bad Request - Your request is invalid. |
401 | Client Error | Unauthorized - Your API key is wrong or not present. |
403 | Client Error | Forbidden - You don't have permissions to access this resource. |
404 | Client Error | Not Found - The resource could not be found. |
405 | Client Error | Method Not Allowed - You tried to access a resource with an invalid method. |
406 | Client Error | Not Acceptable - You requested a format that isn't accepted. |
429 | Client Error | Too Many Requests - You're requesting too many requests ! Slow down! See Limitations. |
500 | Server Error | Internal Server Error - We had a problem with our server. Try again later or report an issue. |
503 | Server Error | Service Unavailable - We're temporarily offline for maintenance. Please try again later. |
Metadata
Example:
"metadata":{
"key1":"value1",
"key2":"value2"
}
Some objects such as Payment
and Merchant
accept a parameter of type Object with additional object metadata in the format of key, value pairs.
The format is:
Field | Type | Format |
---|---|---|
Key | String | max length: 255 |
Value | String | max length: 255 |
Callback (feature not available yet)
Example:
"callback":{
"url":"http://my.callback.url",
"method":"POST"
}
Some objects such as Payment
accept an attribute of type Callback enabling the possibility to declare an url/method to be called anytime there is change in the object status or in any other key attribute change.
The format is:
Field | Type | Format |
---|---|---|
url | String | max length: 2000 |
method | String | One of POST, PUT, DELETE or GET |
The callback request is made passing a pgr-payment-id
header to identify the payment.
The callback mechanism uses the following retry policy: maximum of 5 attemps, 2 seconds between each attempt.
Pagination and Sorting
Some endpoints that might return extense sets of data, such as /merchants/payments
and /merchants/transactions/
accept pagination and sorting parameters.
These parameters are passed as part of the url:
Parameter | Description | Examples | Default |
---|---|---|---|
page | Page index | page=0 (first page) | 0 |
size | Max number of results per request | size=50 | 10 |
sort | field(s) to apply sorting when returning results | sort=created,DESC - sorts by descending creation date sort=created,DESC&sort=externalId,ASC - sorts by descending creation date and ascending externalId |
sort=created,ASC - sorts by ascending creation date |
Example 1 (Pagination/PageNumber):
https://merchants-api.payger.com/api/v1/merchants/payments?page=5
Example 2 (Pagination/PageSize):
https://merchants-api.payger.com/api/v1/merchants/transactions?size=50
Example 3 (Pagination and Sort):
https://merchants-api.payger.com/api/v1/merchants/transactions?page=2&size=20&sort=created,ASC&sort=status,DESC
Response (Pagination and Sort Transactions):
{
"content":[
{
"id":"transaction1",
"externalRef":"payment1",
"description":"description1",
"type":"PAYMENT",
"status":"NEW",
"merchantId":"merchant1",
"timestamp":"2018-04-11 16:02:33"
},
{
"id":"transaction2",
"externalRef":"payment2",
"description":"description2",
"type":"PAYMENT",
"status":"NEW",
"merchantId":"merchant1",
"timestamp":"2018-04-11 16:02:33"
}
],
"size": 20,
"page": 2,
"pageElements": 2
}
Limitations (feature not available yet)
To ensure consistent access to API resources and prevent abuse that can impact performance for all users, all endpoints have rate limits in place. These limits are applied by user account (Token).
Each Token will be limited to NNNN requests per hour.
Idempotent requests
Example (Idempotent Request):
curl -X POST \
https://merchants-api.payger.com/api/v1/merchants/payments/ \
-H 'Authorization: Bearer eyJ...' \
-H 'Content-Type: application/json' \
-H 'pgr-idempotency: cbdd64d5-8493-404e-909c-b118d8caa0ef' \
-d '{
"externalId":"ext12345",
"description":"description",
"paymentCurrency":"BTC",
"productCurrency":"USD",
"source":"string",
"productAmount":"0.003",
"buyerName":"buyer",
"buyerEmailAddress":"test@test.com",
"ipAddress":"10.10.10.1",
"latitude":"12.3211",
"longitude":"-11.585274",
"callback":{
"url":"http://demo.com",
"method":"POST",
"params":{
"orderID":"12345"
}
},
"metadata":{
"a":"b"
}
}'
As a safety feature, this API supports an Idempotency Identifier in all the relevant requests: POST
and PUT
.
This will allow the user to safely retry the same request twice, obtaining the same response, if the same Idempotency Identifier is passed. This may happen due to some code error, network error, JMS or Database rollback, etc. In this case, if using the Idempotency Identifier, the API garantees that the request is executed once only.
To perform an idempotent request, provide an additional pgr-idempotency
header to the request. The maximum lenght is 40. Anything above will result in an HTTP error code 400.
If not using the Idempotency Identifier, or passing a blank value, all the relevant requests will always be processed.
Please use random strings and do not repeat. We suggest UUID's or some equivalent unique identifier generation algorithm.
At the moment these IDs do not expire.
Merchants Endpoints
Payments
Use the Payments endpoint /merchants/payments
to create, update, add payment address, cancel, show details and list payments.
The Payment
object attributes:
Attribute | Description | Source |
---|---|---|
id String |
Payment unique identifier | generated |
externalId String |
External identifier | user provided |
description String |
Free text description | user provided |
status String |
Status One of: PENDING, PAID, CANCELLED, UNDERPAID, OVERPAID, EXPIRED, FAILED |
generated |
merchantId String |
Merchant identifier | generated |
created Timestamp |
Creation timestamp | generated |
lastUpdated Timestamp |
Last update timestamp | generated |
source String |
Source description | user provided |
buyerName String |
Buyer Name | user provided |
buyerEmailAddress String |
Buyer Email | user provided |
callback Object |
Callback | user provided |
metadata Object |
Metadata | user provided |
subPayments List of SubPayment |
SubPayments detected as part of the initial payment request | generated |
The SubPayment
object attributes:
Attribute | Description | Source |
---|---|---|
paymentCurrency String |
Payment currency identifier | user provided |
paymentAmount Number |
Payment Amount | generated applying the exchange rate (internally) |
productCurrency String |
Product currency identifier | user provided |
productAmount Number |
Product Amount | user provided |
address String |
Payment address | generated |
qrCode Object |
QrCode | generated |
created Timestamp |
Creation timestamp | generated |
lastUpdated Timestamp |
Last update timestamp | generated |
ipAddress String |
IP address | user provided |
latitude Number |
Latitude global coordinate | user provided |
longitude Number |
Longitude global coordinate | user provided |
status String |
Status | generated |
Create a payment
Example request (Create a payment):
"POST https://merchants-api.payger.com/api/v1/merchants/payments/"
{
"externalId":"externalId",
"description":"description",
"paymentCurrency":"BTC",
"productCurrency":"USD",
"productAmount":"0.001",
"source":"source",
"buyerName":"buyerName",
"buyerEmailAddress":"buyerEmailAddress@buyer.com",
"ipAddress":"10.10.10.1",
"latitude":"10.123456",
"longitude":"-10.123456",
"callback":{
"url":"http://demo.com",
"method":"POST",
"params":{
"orderID":"123456"
}
},
"metadata":{
"a":"b"
}
}
curl -X POST https://merchants-api.payger.com/api/v1/merchants/payments/ \
-H 'Authorization: Bearer eyJhbGc...' \
-H 'Content-Type: application/json' \
-d '{
"externalId":"externalId",
"description":"description",
"paymentCurrency":"BTC",
"productCurrency":"USD",
"productAmount":"0.001",
"source":"source",
"buyerName":"buyerName",
"buyerEmailAddress":"buyerEmailAddress@buyer.com",
"ipAddress":"10.10.10.1",
"latitude":"10.123456",
"longitude":"-10.123456",
"callback":{
"url":"http://demo.com",
"method":"POST",
"params":{
"orderID":"123456"
}
},
"metadata":{
"a":"b"
}
}'
$args = array (
'externalId' => '001',
'description' => 'Description',
'inputCurrency' => 'BTC',
'outputCurrency' => 'USD',
'source' => 'Your Website',
'outputAmount' => 3.0,
'buyerName' => 'Buyer Name',
'buyerEmailAddress' => 'Buyer Address',
'callback' => array( 'url' => 'Callback URL', 'method' => 'POST' ),
);
$response = Payger::post( 'merchants/payments/', $args );
const oauth2 = {
apiKey: APIKEY,
apiSecret: APISECRET
};
const basicAuth = {
user: USERNAME,
psw: ""
};
const actions = {
getBalances: "GET_BALANCES",
getCurrencies: "GET_CURRENCIES",
getCurrency: "GET_CURRENCY",
getExchangeRate: "GET_EXCHANGERATES",
getPaymentLimits: "GET_PAYMENTLIMITS",
getAllTransactions: "GET_ALLTRANSACTIONS",
getTransactions: "GET_TRANSACTIONS",
getTransaction: "GET_TRANSACTION",
getPayments: "GET_PAYMENTS",
savePayment: "SAVE_PAYMENTS",
getPayment: "GET_PAYMENT",
updatePayment: "UPDATE_PAYMENT",
cancelPayment: "CANCEL_PAYMENT",
addAddress: "ADD_ADDRESS",
getFees: "GET_FEES",
};
const merchant = new Merchant('production', oauth2, basicAuth);
const data= {
"externalId":"EXTERNAL_ID",
"description":"description",
"paymentCurrency":"BTC",
"productCurrency":"USD",
"source":"source",
"productAmount":"0.001",
"buyerName":"buyerName",
"buyerEmailAddress":"buyerEmailAddress@buyer.com",
"ipAddress":"10.10.10.1",
"latitude":"12.123456",
"longitude":"-11.123456",
"callback":{
"url":"http://mywebsite.com/57B25E6B-A877-4102-ADC5-473A9E701ED5",
"method":"POST",
"params":{
"orderID":"57B25E6B-A877-4102-ADC5-473A9E701ED5"
}
},
"metadata":{
"property1":"value1"
}
}
const content = await merchant.call(actions.savePayment, JSON.stringify(data)).then(function(response) {
return response.content;
});
Example response (Create a payment):
{
"content":{
"id":"cf73bde0-b1eb-11e8-ad26-ed6bc2411edd",
"externalId":"externalId",
"description":"description",
"status":"PENDING",
"merchantId":"ef9447f1-2e94-11e8-914a-87ad04da7527",
"created":"2018-09-06 15:44:59",
"lastUpdated":"2018-09-06 15:44:59",
"callback":{
"url":"http://mywebsite.com/57B25E6B-A877-4102-ADC5-473A9E701ED5",
"method":"POST",
"params":{
"orderID":"57B25E6B-A877-4102-ADC5-473A9E701ED5"
}
},
"metadata":{
"property1":"value1"
},
"subPayments":[
{
"paymentCurrency":"BTC",
"paymentAmount":"0.00000186",
"productCurrency":"USD",
"productAmount":"0.001",
"address":"33seMQkSdgomkoHuNv9hQfZSxsxjCouU9Y",
"qrCode":{
"content":"iVBOR...",
"fileSize":250,
"fileType":"png",
"encoding":"UTF-8"
},
"created":"2018-09-06 15:44:59",
"lastUpdated":"2018-09-06 15:44:59",
"ipAddress":"10.10.10.1",
"latitude":"12.123456",
"longitude":"-11.123456",
"status":"pending"
}
],
"fee":{
"feeInProductCurrency":{
"currency":"USD",
"fee":"0.0008924731182795699"
},
"feeInPaymentCurrency":{
"currency":"BTC",
"fee":"0.00000166"
}
},
"source":"source",
"buyerName":"buyerName",
"buyerEmailAddress":"buyerEmailAddress@buyer.com"
},
"timestamp":"2018-09-06 15:44:59"
}
POST /merchants/payments
The API will generate a new payment object and call PAYGER's backend to initiate a payment operation.
The corresponding paymentAmount
is calculated applying the current exchange rate for the conversion productCurrency
>paymentCurrency
for the required amount, plus fees (see Fee object returned by the API). A new qrCode with the payment address is returned to the user, so he is able to transfer the funds.
Fields id
, status
, merchantId
, created
, lastUpdated
, fee
and subPayments
list will be returned automatically by the API.
Update a payment
PUT /merchants/payments/{id}
The API will update the existing payment object with new description
, externalId
and metadata
.
Field lastUpdated
will be set automatically by the API.
Example request (Update a payment):
"PUT https://merchants-api.payger.com/api/v1/merchants/payments/"
{
"externalId": "EXTERNAL_ID",
"description" : "new description",
"metadata" : {
"property" : "new property"
}
}
curl -X PUT https://merchants-api.payger.com/api/v1/merchants/payments/ \
-H 'Authorization: Bearer eyJhbGc...' \
-H 'Content-Type: application/json' \
-d '{
"externalId": "EXTERNAL_ID",
"description" : "new description",
"metadata" : {
"property" : "new property"
}
}'
const data = {
"externalId": "EXTERNAL_ID",
"description" : "new description",
"metadata" : {
"property" : "new property"
}
};
const content= await merchant.call(actions.updatePayment, { id: PAYMENT_ID, values: JSON.stringify(data) }).then(function(response) {
return response.content;
});
Example response (Update a payment):
{
"content": {
"buyerEmailAddress": "string",
"buyerName": "string",
"callback": {
"method": "POST",
"params": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"url": "http://mywebsite.com/payments/12345"
},
"created": "2018-01-01 12:34:56",
"description": "This is a description",
"externalId": "EXT123456789",
"fee": {
"feeInPaymentCurrency": {
"currency": "USD",
"fee": 1234.5678
},
"feeInProductCurrency": {
"currency": "USD",
"fee": 1234.5678
}
},
"lastUpdated": "2018-01-01 12:34:56",
"merchantId": "f5acfb30470011e8842f0ed5f89f718b",
"source": "string",
"status": "PAID",
"id": "f5acfb30470011e8842f0ed5f89f718b",
"metadata": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"subPayments": [
{
"actualProductAmount": 1234.5678,
"address": "string",
"created": "2018-01-01 12:34:56",
"ipAddress": "string",
"lastUpdated": "2018-01-01 12:34:56",
"latitude": 0,
"longitude": 0,
"paymentAmount": 1234.5678,
"paymentCurrency": "BTC",
"productAmount": 1234.5678,
"productCurrency": "USD",
"qrCode": {
"content": "string",
"encoding": "UTF-8",
"fileSize": 250,
"fileType": "png"
},
"status": "string"
}
]
},
"timestamp": "2018-01-01 12:34:56"
}
Cancel a payment
Example request (Cancel a payment):
"DELETE https://merchants-api.payger.com/api/v1/merchants/payments/5266b200-b059-11e8-beb1-f5d297a593b6"
curl -X DELETE https://merchants-api.payger.com/api/v1/merchants/payments/5266b200-b059-11e8-beb1-f5d297a593b6 \
-H 'Authorization: Bearer eyJhbGc...'
const content = await merchant.call(actions.cancelPayment, PAYMENT_ID).then(function(response) {
return response.content;
});
Example response (Cancel a payment):
{
"content": {
"buyerEmailAddress": "string",
"buyerName": "string",
"callback": {
"method": "POST",
"params": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"url": "http://mywebsite.com/payments/12345"
},
"created": "2018-01-01 12:34:56",
"description": "This is a description",
"externalId": "EXT123456789",
"fee": {
"feeInPaymentCurrency": {
"currency": "USD",
"fee": 1234.5678
},
"feeInProductCurrency": {
"currency": "USD",
"fee": 1234.5678
}
},
"lastUpdated": "2018-01-01 12:34:56",
"merchantId": "f5acfb30470011e8842f0ed5f89f718b",
"source": "string",
"status": "PAID",
"id": "f5acfb30470011e8842f0ed5f89f718b",
"metadata": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"subPayments": [
{
"actualProductAmount": 1234.5678,
"address": "string",
"created": "2018-01-01 12:34:56",
"ipAddress": "string",
"lastUpdated": "2018-01-01 12:34:56",
"latitude": 0,
"longitude": 0,
"paymentAmount": 1234.5678,
"paymentCurrency": "BTC",
"productAmount": 1234.5678,
"productCurrency": "USD",
"qrCode": {
"content": "string",
"encoding": "UTF-8",
"fileSize": 250,
"fileType": "png"
},
"status": "string"
}
]
},
"timestamp": "2018-01-01 12:34:56"
}
DELETE /merchants/payments/{id}
The API will cancel the existing payment object, if found, and if the payment is not being processed by PAYGER backend yet.
Field lastUpdated
will be set automatically by the API.
Add address to payment
Example request (Add address to payment):
"POST https://merchants-api.payger.com/api/v1/merchants/payments/5266b200-b059-11e8-beb1-f5d297a593b6/address"
{
"paymentCurrency": "BTC"
}
curl -X POST https://merchants-api.payger.com/api/v1/merchants/payments/5266b200-b059-11e8-beb1-f5d297a593b6/address \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer eyJhbGc...' \
-d '{
"paymentCurrency": "BTC"
}
'
const data = {
"paymentCurrency":"BTC"
};
const content = await merchant.call(actions.addAddress, { id: PAYMENT_ID, address: JSON.stringify(data) }).then(function(response) {
return response.content;
});
Example response (Add address to payment):
{
"content": {
"buyerEmailAddress": "string",
"buyerName": "string",
"callback": {
"method": "POST",
"params": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"url": "http://mywebsite.com/payments/12345"
},
"created": "2018-01-01 12:34:56",
"description": "This is a description",
"externalId": "EXT123456789",
"fee": {
"feeInPaymentCurrency": {
"currency": "USD",
"fee": 1234.5678
},
"feeInProductCurrency": {
"currency": "USD",
"fee": 1234.5678
}
},
"lastUpdated": "2018-01-01 12:34:56",
"merchantId": "f5acfb30470011e8842f0ed5f89f718b",
"source": "string",
"status": "PAID",
"id": "f5acfb30470011e8842f0ed5f89f718b",
"metadata": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"subPayments": [
{
"actualProductAmount": 1234.5678,
"address": "string",
"created": "2018-01-01 12:34:56",
"ipAddress": "string",
"lastUpdated": "2018-01-01 12:34:56",
"latitude": 0,
"longitude": 0,
"paymentAmount": 1234.5678,
"paymentCurrency": "BTC",
"productAmount": 1234.5678,
"productCurrency": "USD",
"qrCode": {
"content": "string",
"encoding": "UTF-8",
"fileSize": 250,
"fileType": "png"
},
"status": "string"
}
]
},
"timestamp": "2018-01-01 12:34:56"
}
POST /merchants/payments/{id}/address
The API will add a new address (for a specified productAmount) to an existing payment, using the same paymentCurrency.
Field lastUpdated
will be set automatically by the API and subPayments
list will contain the new subPayment
, ordered by creation date, descending.
Get payment info
Example request (Get payment info):
"GET https://merchants-api.payger.com/api/v1/merchants/payments/403ed080-b054-11e8-beb1-f5d297a593b6"
curl -X GET https://merchants-api.payger.com/api/v1/merchants/payments/403ed080-b054-11e8-beb1-f5d297a593b6
-H 'Authorization: Bearer eyJhbGc...'
const content = await merchant.call(actions.getPayment, PAYMENT_ID).then(function(response) {
return response.content;
});
Example response (Get payment info):
{
"content": {
"buyerEmailAddress": "string",
"buyerName": "string",
"callback": {
"method": "POST",
"params": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"url": "http://mywebsite.com/payments/12345"
},
"created": "2018-01-01 12:34:56",
"description": "This is a description",
"externalId": "EXT123456789",
"fee": {
"feeInPaymentCurrency": {
"currency": "USD",
"fee": 1234.5678
},
"feeInProductCurrency": {
"currency": "USD",
"fee": 1234.5678
}
},
"lastUpdated": "2018-01-01 12:34:56",
"merchantId": "f5acfb30470011e8842f0ed5f89f718b",
"source": "string",
"status": "PAID",
"id": "f5acfb30470011e8842f0ed5f89f718b",
"metadata": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"subPayments": [
{
"actualProductAmount": 1234.5678,
"address": "string",
"created": "2018-01-01 12:34:56",
"ipAddress": "string",
"lastUpdated": "2018-01-01 12:34:56",
"latitude": 0,
"longitude": 0,
"paymentAmount": 1234.5678,
"paymentCurrency": "BTC",
"productAmount": 1234.5678,
"productCurrency": "USD",
"qrCode": {
"content": "string",
"encoding": "UTF-8",
"fileSize": 250,
"fileType": "png"
},
"status": "string"
}
]
},
"timestamp": "2018-01-01 12:34:56"
}
GET /merchants/payments/{id}
The API will return the payment object, if found.
Get all payments info
Example request (Get all payments info):
"GET https://merchants-api.payger.com/api/v1/merchants/payments/"
curl -X GET https://merchants-api.payger.com/api/v1/merchants/payments/
-H 'Authorization: Bearer eyJhbGc...'
const data = {
page: 1,
size: 10,
sort: "created,desc"
};
const content = await merchant.call(actions.getPayments, data).then(function(response) {
return response.content;
});
Example response (Get all payments info):
{
"content": [
{
"buyerEmailAddress": "string",
"buyerName": "string",
"callback": {
"method": "POST",
"params": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"url": "http://mywebsite.com/payments/12345"
},
"created": "2018-01-01 12:34:56",
"description": "This is a description",
"externalId": "EXT123456789",
"fee": {
"feeInPaymentCurrency": {
"currency": "USD",
"fee": 1234.5678
},
"feeInProductCurrency": {
"currency": "USD",
"fee": 1234.5678
}
},
"lastUpdated": "2018-01-01 12:34:56",
"merchantId": "f5acfb30470011e8842f0ed5f89f718b",
"source": "string",
"status": "PAID",
"id": "f5acfb30470011e8842f0ed5f89f718b",
"metadata": {
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
},
"subPayments": [
{
"actualProductAmount": 1234.5678,
"address": "string",
"created": "2018-01-01 12:34:56",
"ipAddress": "string",
"lastUpdated": "2018-01-01 12:34:56",
"latitude": 0,
"longitude": 0,
"paymentAmount": 1234.5678,
"paymentCurrency": "BTC",
"productAmount": 1234.5678,
"productCurrency": "USD",
"qrCode": {
"content": "string",
"encoding": "UTF-8",
"fileSize": 250,
"fileType": "png"
},
"status": "string"
}
]
}
],
"page": 0,
"pageElements": 0,
"size": 0,
"timestamp": "2018-01-01 12:34:56"
}
GET /merchants/payments
The API will return all the payment objects associated with the current merchant account.
This endpoint supports sorting, passing the criteria as url parameters:
Parameter | Description |
---|---|
description |
Filter by description (contains) |
paymentCurrency |
Filter by inputCurrency (contains) |
productCurrency |
Filter by outputCurrency (contains) |
externalId |
Filter by externalId (contains) |
createdFrom |
Filter by creation date (after) |
createdTo |
Filter by creation date (before) |
lastUpdatedFrom |
Filter by updated date (after) |
lastUpdatedTo |
Filter by updated date (before) |
paymentAmountFrom |
Filter by paymentAmount (greater or equal to) |
paymentAmountTo |
Filter by paymentAmount (smaller or equal to) |
productAmountFrom |
Filter by productAmount (greater or equal to) |
productAmountTo |
Filter by productAmount (smaller or equal to) |
Payment Limits
Use the Payment Limits endpoint /merchants/payment-limits
to get payment limits for a specified pair of currencies. This may be the result of a liquidity restrition imposed by the payments bridge.
The PaymentLimit object attributes:
Attribute | Description |
---|---|
currency String |
Currency identifier |
amount Number |
Limit Amount |
precision Byte |
Currency precision |
Get payment limits for pair paymentCurrency,productCurrency
Example request (Get payment limits):
"GET https://merchants-api.payger.com/api/v1/merchants/payment-limits/BTC/USD"
curl -X GET https://merchants-api.payger.com/api/v1/merchants/payment-limits/BTC/USD \
-H 'Authorization: Bearer eyJhbGc...'
const data = {
inputCurrency: "BTC",
outputCurrency: "BTS"
};
const content = await merchant.call(actions.getPaymentLimits, data).then(function(response) {
return response.content;
});
Example response (Get payment limits):
{
"content": {
"amount": 1234.5678,
"currency": "BTC",
"precision": 8
},
"timestamp": "2018-01-01 12:34:56"
}
GET /merchants/payment-limits/{paymentCurrency}/{productCurrency}
The API will return the payment limits object, if this conversion is supported.
Exchange Rates
Use the Exchange Rates endpoint /merchants/exchange-rates
to get exchange rates from a specified currency to another or all other currencies.
The Exchange Rate object attributes:
Attribute | Description |
---|---|
rates Array |
Collection of rates to the different currencies |
rate.currency String |
Target currency |
rate.rate Number |
Exchange rate |
rate.limit Number |
Limit amount accepted (only if applyLimits=true parameter is applied) |
rate.amount Number |
Amount converted to the target currency |
amount Number |
Amount provided |
Get all exchange rates limits
Example request (Get Exchange Rates):
"GET 'https://merchants-api.payger.com/api/v1/merchants/exchange-rates?productCurrency=USD&applyLimits=true&amount=2'"
curl -X GET 'https://merchants-api.payger.com/api/v1/merchants/exchange-rates?productCurrency=USD&applyLimits=true&amount=2' \
-H 'Authorization: Bearer eyJhbGciOi...'
const data = {
productCurrency: "USD",
amount: 10,
applyLimits: false
};
const content = await merchant.call(actions.getExchangeRate, data).then(function(response) {
return response.content;
});
Example response (Get Exchange Rates):
{
"content": {
"amount": 1234.5678,
"productCurrency": "BTC",
"rates": [
{
"amount": 1234.5678,
"currency": "BTC",
"limit": 1234.5678,
"precision": 8,
"rate": 1234.5678
}
]
},
"timestamp": "2018-01-01 12:34:56"
}
GET /merchants/exchange-rates
The API will return all the exchange rate objects from a specified currency to another, if found. Also, if an amount is provided it will make the conversion. We can filter by limits also.
This endpoint supports the parameters:
Parameter | Description |
---|---|
productCurrency String, Required |
Currency in which the merchant has a defined product price |
paymentCurrencies String |
Currency(ies) in which the payment will be made - if ommited will show all. Also accepts a comma separated list. |
applyLimits Boolean |
Whether we should only return the currencies under the limits after conversion for this amount. This parameter works in conjunction with the amount parameter |
amount Number, Required |
Amount to apply the rate |
Transactions
Use the Transactions endpoint /merchants/transactions
to get a specific transaction details or list transactions.
The Transaction object attributes:
Attribute | Description |
---|---|
id String |
Unique identifier of the transaction |
description String |
Description |
status String |
Status One of: NEW or CANCELLED |
type String |
Type One of: PAYMENT or REFUND |
currency String |
Currency identifier |
amount Number |
Amount |
merchantId String |
Merchant identifier |
created Timestamp |
Creation timestamp |
additionalInfo Object |
Object with payment specific info (for payment type transactions) |
Get all merchant's transactions
Example request (Get all merchant's transactions):
"GET https://merchants-api.payger.com/api/v1/merchants/transactions/"
curl -X GET https://merchants-api.payger.com/api/v1/merchants/transactions/ \
-H 'Authorization: Bearer eyJhbGciOi...'
const data = {
page: 1,
size: 10
};
const content = await merchant.call(actions.getTransactions, data).then(function(response) {
return response.content;
});
Example response (Get all merchant's transactions):
{
"content": [
{
"amount": 1234.5678,
"created": "2018-01-01 12:34:56",
"currency": "BTC",
"description": "This is a description",
"id": "f5acfb30470011e8842f0ed5f89f718b",
"merchantId": "4bd9010ab8b94aa7ad22ec9a02611ebf",
"status": "NEW",
"type": "PAYMENT"
}
],
"page": 0,
"pageElements": 0,
"size": 0,
"timestamp": "2018-01-01 12:34:56"
}
GET /merchants/transactions
The API will return all the merchant's transaction objects details, if found.
This endpoint supports filters, passing the criteria as url parameters:
Transaction filters:
Parameter | Description |
---|---|
currency |
Filter by currency (contains) |
createdFrom |
Filter by creation date (after) |
createdTo |
Filter by creation date (before) |
Payment specific filters:
Parameter | Description |
---|---|
externalId |
Filter by payment externalId (contains) |
paymentId |
Filter by paymentId (contains) |
inputCurrency |
Filter by payment inputCurrency (contains) |
outputCurrency |
Filter by payment outputCurrency (contains) |
paymentDescription |
Filter by payment description (contains) |
paymentStatus |
Filter by payment status (equals) |
paymentAddress |
Filter by payment address (contains) |
paymentMemo |
Filter by payment memo (contains) |
inputAmountFrom |
Filter by payment inputAmount (greater or equal to) |
inputAmountTo |
Filter by payment inputAmount (smaller or equal to) |
outputAmountFrom |
Filter by payment outputAmount (greater or equal to) |
outputAmountTo |
Filter by payment outputAmount (smaller or equal to) |
Get a transaction details
Example request (Get a transaction details):
"GET https://merchants-api.payger.com/api/v1/merchants/transactions/e6f31da0-9a6f-11e8-ab04-15fc944b3337"
curl -X GET https://merchants-api.payger.com/api/v1/merchants/transactions/e6f31da0-9a6f-11e8-ab04-15fc944b3337 \
-H 'Authorization: Bearer eyJhbGciOi...'
const content = await merchant.call(actions.getTransaction, "TRANSACTION_ID").then(function(response) {
return response.content;
});
Example response (Get all exchange rates limits):
{
"content": {
"amount": 1234.5678,
"created": "2018-01-01 12:34:56",
"currency": "BTC",
"description": "This is a description",
"id": "f5acfb30470011e8842f0ed5f89f718b",
"merchantId": "4bd9010ab8b94aa7ad22ec9a02611ebf",
"status": "NEW",
"type": "PAYMENT"
},
"timestamp": "2018-01-01 12:34:56"
}
GET /merchants/transactions/{id}
The API will return the transaction object details, if found.
Balances
Use the Balances endpoint /merchants/balances
to get the balance of the different merchant's currencies.
The Balance object attributes:
Attribute | Description |
---|---|
currency String |
Currency identifier |
balance Number |
Balance of the currency |
precision Byte |
Balance amount precision |
Get all merchant's currencies balance
Example request (Balances):
"GET https://merchants-api.payger.com/api/v1/merchants/balances/"
curl -X GET https://merchants-api.payger.com/api/v1/merchants/balances/ \
-H 'Authorization: Bearer eyJhbGciOi...'
const content = await merchant.call(actions.getBalances).then(function(response) {
return response.content;
});
Example response (Balances):
{
"content": [
{
"balance": 1234.5678,
"currency": "BTC",
"precision": 8
}
],
"timestamp": "2018-01-01 12:34:56"
}
GET /merchants/balances
The API will return all the merchant's assets balance, if found.
Fees
Use the Fees endpoint /merchants/fees
to get the fee amount in both product and payment currencies.
The Fee object attributes:
Attribute | Description |
---|---|
feeInProductCurrency CurrencyFee |
Fee in product currency |
feeInPaymentCurrency CurrencyFee |
Fee in payment currency |
The CurrencyFee object attributes:
Attribute | Description |
---|---|
currency String |
Currency identifier |
fee Number |
Amount of Fee (in the specified currency) |
Get Payment fee
Example request (Get Payment fee):
"POST https://merchants-api.payger.com/api/v1/merchants/payments/"
{
"paymentCurrency": "BTC",
"productAmount": "1",
"productCurrency": "USD"
}'
curl -X POST https://merchants-api.payger.com/api/v1/merchants/payments/ \
-H 'Authorization: Bearer eyJhbGc...' \
-H 'Content-Type: application/json' \
-d '{
"paymentCurrency": "BTC",
"productAmount": "1",
"productCurrency": "USD"
}'
const feeRequest = {
"paymentCurrency":"BTC",
"productCurrency":"USD",
"productAmount":"0.15"
};
const content = await merchant.call(actions.getFees, JSON.stringify(feeRequest)).then(function(response) {
return response.content;
});
Example response (Get Payment fee):
{
content:{
feeInProductCurrency:{
currency:'USD',
fee:'0.010676156583629892'
},
feeInPaymentCurrency:{
currency:'BTC',
fee:'0.0000018'
}
},
timestamp:'2018-10-02 14:45:10'
}
POST /merchants/fees
The API will return the amount to pay in relation to fees in a certain payment request.
Currencies
Use the Currencies endpoint /merchants/currencies
to get API supported currencies information, such as names, precision icons and mapping to another currencies.
The Currency object attributes:
Attribute | Description |
---|---|
name String |
Name |
longName String |
Long name |
precision Byte |
Precision |
icon Object |
Icon object |
The Icon object attributes:
Attribute | Description |
---|---|
smallIconUrl Object |
Small Icon url |
mediumIconUrl Object |
Medium Icon url |
Get all currencies
Example request (Get all currencies):
"GET https://merchants-api.payger.com/api/v1/merchants/currencies"
curl -X GET https://merchants-api.payger.com/api/v1/merchants/currencies \
-H 'Authorization: Bearer ...'
const content = await merchant.call(actions.getCurrencies).then(function(response) {
return response.content;
});
Example response (Get all currencies):
{
"content": {
"currencies": [
{
"icon": {
"mediumIconUrl": "string",
"smallIconUrl": "string"
},
"longName": "Bitcoin",
"name": "BTC",
"precision": 8
}
],
"paymentCurrency": "BTC",
"productCurrency": "BTC"
},
"timestamp": "2018-01-01 12:34:56"
}
GET /merchants/currencies
The API will return all the supported currencies information.
This endpoint supports the parameters:
Parameter | Description |
---|---|
productCurrency String |
to return only currencies that can be converted into that product currency |
paymentCurrency String |
to return only currencies in which a product can display its price |
If any of the parameters are applied the results will be filtered, otherwise the API returns all the supported currencuies.
Get a currency
Example request (Get a currency):
"GET https://merchants-api.payger.com/api/v1/merchants/currencies/BTC"
curl -X GET https://merchants-api.payger.com/api/v1/merchants/currencies/BTC \
-H 'Authorization: Bearer eyJhbGc...'
const content = await merchant.call(actions.getCurrency, "BTC").then(function(response) {
return response.content;
});
Example response (Get a currency):
{
"content": {
"icon": {
"mediumIconUrl": "string",
"smallIconUrl": "string"
},
"longName": "Bitcoin",
"name": "BTC",
"precision": 8
},
"timestamp": "2018-01-01 12:34:56"
}
GET /merchants/currencies/{currency}
The API will return the currency information, if existent.
How-To
Create a new payment (Merchants)
Example: Suppose I own an ECommerce website, and I have a valid Merchant account with Payger. I'm working with US Dollars (USD) and I want to sell a product worth 100 US Dollars, accepting a Bitcoin (BTC) payment.
To use this API to accept the payment I must:
1 - Get a valid API key/secret
Access Payger Wallet to generate a new API key/secret pair.
2 - Get a new API token
With this pair (key/secret) call the url
POST /oauth/token?grant_type=password&username=<API_KEY>&password=<API_SECRET>
Using Basic HTTP authentication.
The OAuth client auth should be: Username: "netevia", "payger" or "payger_wc_plugin". Password: Empty string
Get the valid token from the attribute access_token
3 - Get a quote
Call the ExchangeRates endpoint to get a quote for the currency conversion:
GET /merchants/exchange-rates?productCurrency=<PRODUCT_CURRENCY>&paymentCurrency=<PAYMENT_CURRENCY>&amount=<AMOUNT>
Parameter | Description | Value |
---|---|---|
productCurrency |
Currency in which we are currently selling the product on our website | US Dollars (USD) |
paymentCurrency |
Currency in which the payment will be accepted | Bitcoin (BTC) |
amount |
Amount | 100 |
URL:
GET /merchants/exchange-rates?productCurrency=USD&amount=100&paymentCurrency=BTC
Example response (Get Exchange Rate):
{
"content": {
"rates": [
{
"currency": "BTC",
"rate": "0.00017028060000000002",
"amount": "0.01702806",
"precision": 8
}
],
"productCurrency": "USD",
"amount": "100"
},
"timestamp": "2018-08-17 15:01:53"
}
The amount is just a quote that Payger API provides to the user to buy bitcoin worth of 100 USD. This quote should be displayed to the user when creating the UI payment button.
4 - Get the fee amount (optional)
Call the Fees endpoint to get an estimated Fee amount. This can be presented to the user as this amount will be included in the total amount of the payment. Later when creating the payment, the final Fee amount will be provided.
POST /merchants/fees/
Example request (Get Fee):
{
"paymentCurrency": "BTC",
"productAmount": "100",
"productCurrency": "USD"
}
Example response (Get Fee):
{
"content": {
"feeInProductCurrency": {
"currency": "USD",
"fee": "0.009036472509526402"
},
"feeInPaymentCurrency": {
"currency": "BTC",
"fee": "0.00000166"
}
},
"timestamp": "2018-09-06 15:21:55"
}
5 - Create the payment request
Call the Payments endpoint to initiate a new payment. Reuse the same productCurrency and productAmount.
POST /merchants/payments
Example request (Create Payment):
POST /merchants/payments
{
"externalId":"0000000001",
"description":"ECommerce payment order 0000000001",
"paymentCurrency": "BTC",
"productCurrency": "USD",
"productAmount": "100",
"source":"string",
"buyerName":"buyerName",
"buyerEmailAddress":"test@test.com",
"ipAddress":"10.10.10.1",
"latitude":"10.123456",
"longitude":"-11.123456",
"callback":{
"url":"http://demo.com",
"method":"POST",
"params":{
"orderID":"123456"
}
},
"metadata":{
"brand" : "Acme",
"color" : "red",
"original value" : "100 usd"
}
}
Example response (Create Payment):
{
"content":{
"id":"cb84dee0-a231-11e8-83f4-f39d574b416d",
"externalId":"0000000001",
"description":"ECommerce payment order 0000000001",
"status":"PENDING",
"merchantId":"ef9447f1-2e94-11e8-914a-87ad04da7527",
"created":"2018-08-17 15:25:38",
"lastUpdated":"2018-08-17 15:25:38",
"callback":{
"url":"http://demo.com",
"method":"POST",
"params":{
"orderID":"123456"
}
},
"metadata":{
"brand":"Acme",
"color":"red",
"original value":"100 usd"
},
"subPayments":[
{
"paymentCurrency":"BTC",
"paymentAmount":"0.01536078",
"productCurrency":"USD",
"productAmount":"100",
"address":"38zZhBdZCVw7qAuPNfEvzSs9oiEf2h8qkE",
"qrCode":{
"content":"iVBO...",
"fileSize":250,
"fileType":"png",
"encoding":"UTF-8"
},
"created":"2018-08-17 15:25:38",
"lastUpdated":"2018-08-17 15:25:38",
"ipAddress":"10.10.10.1",
"longitude":"-11.585274",
"status":"pending"
}
],
"fee":{
"feeInProductCurrency":{
"currency":"USD",
"fee":"0.0008924731182795699"
},
"feeInPaymentCurrency":{
"currency":"BTC",
"fee":"0.00000166"
}
},
"source":"string",
"buyerName":"buyerName",
"buyerEmailAddress":"test@test.com"
},
"timestamp":"2018-08-17 15:25:36"
}
The payment is created with a status of PENDING
and until the API receives the payment notification this will be the payment status.
Important information to retain:
Field | Description |
---|---|
id |
The payment unique identifier |
subPayments.qrCode |
Use this qrCode as a reference to transfer to funds to |
status |
Immediatly after creation the status of the payment is PENDING , later should change to PAID |
fee |
Fees applied (converted to both currencies) |
6 - Check the payment status
Call the Payments endpoint with the payment id
obtained in the previous step to get the current payment status.
GET /merchants/payments/{id}
After the API receives payment notification the subPayments
attribute will return indication that the payment has been made by the user, using the reference in the qrCode. The payment status should then be PAID
.
Example request (Get Payment):
GET /merchants/payments/cb84dee0-a231-11e8-83f4-f39d574b416d
7 - Confirm
In case of successfuly processed payment, the funds are transferred into your merchant PAYGER account.
8 - Callback
If the callback was set, please make sure the url is available to get notifications of any changes in the Payment object.
This functionality is not yet implemented