Developer Portal

To create applications that access Payoneer's Services APIs, developers need to open a Payoneer Developer Account and register the application on the Developer Portal at https://developer.sandbox.payoneer.com/psd2/. A registered application will be assigned a unique Client Id and Client Secret.

Security Notice: Your Client Secret should never be shared, must be kept secret at all times and should only be used from your server-side application.

When creating an account in the developer portal. The QWAC certificate (see section 1.5 below) public key from the certificate .crt file must be entered in the registration form.

To create an application:

• Access the portal, to create an application, click "Create new App"

• Provide a name for the application and configure the Redirect URI

• Click "Submit"

• Once created, the application can be managed by clicking on the App name on the Apps Page

• Credentials for the application in the sandbox environment can be generated or reset from the portal

• The application must be subscribed to an available API plan

  When creating or updating applications, the same certificate code that was provided when creating the account must be submitted.

Considerations

• Applications must be secured with a valid QWAC certificate issued by a known Qualified Trust Service Provider (section 1.5).

• The Redirect URI provided when registering the application must be a valid static sub-resource. Note that this property cannot be dynamically reconfigured during authorization requests for security reasons.

• Users can revoke access to your application at any time. The application must be prepared for this and, if necessary, should request authorization from the user again.

• Standard rate limits apply for all issued access tokens.

Account Id

Beneficiaries wishing to receive payments via Payoneer's platform are required to apply for and be approved for an account before they are able to receive funds. Payoneer assigns an Account Id to each account that uniquely identifies the user for purposes of initiating payment, KYC compliance, reconciliation and other purposes. The user's Account Id is obtained when requesting an Access Token authorizing your application to make calls on behalf of a user on your platform. Some of the actions that can be performed on an account that are relevant for developers are presented below:

Querying account information: 3rd party platforms can retrieve account related information from Payoneer for presenting to users on your platform. The Access Token retrieved for the account is submitted as the bearer in the HTTP header to authenticate the request and the Account Id is passes as a parameter to retrieve the appropriate data.

Applying actions to an Account: Following approval of an account by Payoneer, various actions can be performed through the API with an appropriate Access Token and Account Id in the scope of an account. These include:

• Generate receiving bank accounts for the account in different currencies (USD, EUR, GBP and more). The access token retrieved for the account is submitted as the bearer in the HTTP header to authenticate the request
• Retrieve account statements (PDF) for receiving accounts
• Retrieve a list of ‘early payment’ offers associated with the account

Sandbox Test Environment

The Payoneer Sandbox test environment is a self-contained environment in which 3rd party platforms can prototype and test their integration with Payoneer systems and applications prior to moving applications or websites into a production environment. 3rd party platforms use the Sandbox test environment for managing test accounts and testing associated emails, API credentials and functions.

To access the Sandbox test environment, 3rd party platforms must use a unique set of URLs. The credentials for Sandbox and Production environments are different. When migrating from Sandbox to Production environments, 3rd party platforms will need to change the Base URLs and credentials in their code.

The Base URL for calling the Open API in the sandbox environment is: https://psd2-api.sandbox.payoneer.com/

The Base URL for calling Authorization APIs in the sandbox environment is: https://login.sandbox.payoneer.com

The Base URL for calling the Open API in the production environment is: https://psd2-api.payoneer.com/

The Base URL for calling Authorization APIs in the production environment is: https://login.payoneer.com

To access the developer portal in the Sandbox use the following URL: https://developer.sandbox.payoneer.com/psd2/

Common Calling Conventions

This section provides an overview of the Acme APIs error model.

Error Format

HTTP Requests

Requests are sent using appropriate HTTP verbs depending on the method called; Content-Type: application/json should be applied to request headers. Calls to the ver3 API use the bearer header for delegating authorization of credentials. The method name will be prefixed by the name of the entity to which the call applies, for example /accounts/. Calls to Payoneer’s version 4 API take the form:

{HTTP verb} [Base URL]/{entity name}/{method name}/
-H “Authorization: Bearer {token}”

Document Conventions and Variables

Note the following conventions and variables used in this document:

• Variable appearing in API URLs are italicized and enclosed in curly brackets, for example {account_id}
• [Base URL] is a placeholder for the applicable URL for sandbox or production environment
• Enumeration values used in API calls are not case sensitive

In cases that a request is successful, the API returns a response with HTTP status of 200.

Sample Request

-X GET
https://psd2-api.sandbox.payoneer.com/v4/accounts/{account_id}/balances\
-H "Authorization: Bearer MXVNd2NTcTBlTi94NkZC…"\
-H 'content-type: application/json'
Response    {
    "result": {
        "items": [
            {
                "id": "4366181865108056",
                "type": "BALANCE",
                "currency": "GBP",
                "status": "2",
                "status_description": "Active",
                "available_balance": "20.00",
                "update_time": "2018-03-30T19:28:17Z"
            }, ..
        ],
        "total": 3
    }
}

In cases of failed requests, the API returns a response with HTTP status of 400 or above of the form:

{
    "error": "Unauthorized",
    "error_description": "The access token is not valid for this account",
    "error_details": {
        "code": 401,
        "sub_code": 4012
    }
}

In case of internal error/timeout, resend the API with statistical back-off of 2 minutes (1st retry), 4 minutes (2nd retry), 8 minutes (3rd retry), etc...

Error responses returned in cases of bad input or missing mandatory fields and invalid format take the general form:

Collections

Some endpoints (transactions for example) return a collection in the result. In cases of large collections, a paging mechanism is applied to split the returned collection over multiple API calls. Collections use a common format that enables paging for more results if they exists. A collection object typically contains:

• An items[] array containing the actual result items
• An optional total field containing the total number of available results
• An optional next field containing a relative URL that can be used to retrieve the next batch of results. If the “next” field is absent, no additional pages exist

Date formats

All dates are formatted as recommended by RFC 3339

ISO-8601 with time zone

Postman Collection

Postman is an app designed to help with API development, available both as a desktop app and on the web. While you can access Payoneer APIs using standard network transfer tools, such as **curl**, Postman makes development easier with support for saving requests, using variables, and managing authentication.

First, save your application's **client_id** and **client_secret** (which Payoneer Integration team will provide). You'll use these values to configure the Postman collection and start using the API.

Download the Postman Collection below

For each API in the collection, you can expand the description beneath the title in Postman for more information by clicking the caret icon.