NAV Navbar
json shell javascript php
  • Introduction
  • Authentication
  • API Details
  • Merchants Endpoints
  • How-To
  • More documentation
  • Downloads
  • 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",
        "productCurrency": "USD",
        "productAmount": "0.000024"
    }
    
    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",
        "productCurrency": "USD",
        "productAmount": "0.000024"
    }
    '
    
    const data = {
        "paymentCurrency":"BTC",
        "productCurrency":"USD",
        "productAmount":"0.00001"
    };
    
    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

    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.

    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

    More documentation

    Downloads