Global Payments Made Easy - Payoneer · The Payoneer Sandbox Test Environment is a self-contained...

47
© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. Global Payments Made Easy Implementation Guide for Payoneer Payout Services Version 2.60 August 2016

Transcript of Global Payments Made Easy - Payoneer · The Payoneer Sandbox Test Environment is a self-contained...

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 

 

Global Payments Made Easy

Implementation Guide for Payoneer Payout Services

Version 2.60

August 2016

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      2 

Confidentiality By proceeding, you acknowledge that the information contained herein constitutes valuable property and trade secrets of Payoneer, which are strictly confidential.

You agree that you shall not directly or indirectly:

Use or permit the use of this document for, or in connection with, any other business whatsoever, or for any purpose other than the analysis of the project contemplated hereby, or

Disclose or permit the disclosure of any part of this document to any person or entity other than officers, shareholders or representatives of your same organization who are made aware of the confidential nature of this document and the restrictions on the disclosure or use of its contents and for the purpose stated.

Lastly, you agree to immediately notify Payoneer of the circumstances surrounding any breach of this confidentiality of which you become aware.

THIS DOCUMENT CONSTITUTES INTELLECTUAL PROPERTY OF PAYONEER

COPYRIGHT ©PAYONEER 2016

®ALL RIGHTS RESERVED

For any questions or comments about Payoneer Payout Services or this document, please contact the Payoneer integration team at: [email protected]

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      3 

Table of Contents Confidentiality ............................................................................................................................... 2Table of Contents .......................................................................................................................... 31 Getting Started ...................................................................................................................... 4

1.1 Overview ....................................................................................................................... 41.2 The Process ................................................................................................................. 51.3 Communication Security ............................................................................................ 61.4 Sandbox Test Environment ........................................................................................ 71.5 Common Calling Convention and Authentication ................................................... 7

2 Onboarding Payees ............................................................................................................... 92.1 Payee Sign-up .............................................................................................................. 92.2 Payee Sign-up/Auto Population .............................................................................. 11

3 Instant Process Completion Notifications .......................................................................... 173.1 Payment Method Registration Notifications .......................................................... 173.2 Payee Status Notifications ....................................................................................... 183.3 Payment Notifications ............................................................................................... 183.4 Additional IPCN Notifications ................................................................................... 19

4 The Payoneer API ................................................................................................................ 224.1 Echo ............................................................................................................................. 224.2 GetVersion .................................................................................................................. 234.3 Payment Order Submission ..................................................................................... 234.4 Get Payment Status .................................................................................................. 264.5 Query Account Balance Method ............................................................................. 284.6 Get Payee Details ...................................................................................................... 294.7 Change Payee ID ...................................................................................................... 314.8 Get Payees Report .................................................................................................... 324.9 Get Single Payee Report .......................................................................................... 344.10 Get Unclaimed Payments XML ........................................................................... 354.11 Get Unclaimed Payments CSV ........................................................................... 364.12 Cancel Payment ..................................................................................................... 374.13 Move Payee Program ........................................................................................... 38

Appendix A – XML File Format for Payoneer Mass Payment ..................................................... 41Appendix B – Payoneer Mass Payment CSV File Format ............................................................ 42Appendix C – Field Validations .................................................................................................... 44Appendix D – Setup Payoneer landing site language ................................................................. 46Appendix E – Client’s Account Setup Process ............................................................................. 47

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      4 

1 Getting Started Brief guidance for using this Implementation Guide is provided for your convenience.

Section 1. Getting Started – is intended for all developers.

Section 2.1. Payee Sign-up – is intended for clients who will be redirecting payees to sign up with Payoneer.

This is the only API call that is required for website integration.

Section 2.2. Payee Sign-up/Auto Population – is intended for clients who will be redirecting payees to Payoneer to sign up and wish to auto-populate data fields presented to the payee.

Section 3. Instant Process Completion Notifications – is intended for clients who wish to subscribe to Payoneer’s IPCNs (Instant Process Completion Notification) for receiving feedback regarding payee and payment status changes.

Section 4. Payoneer API – is intended for developers who will be initiating payment instructions directly to the Payoneer platform or require to query the platform for information about payees and payments.

1.1 Overview Payoneer provides a complete and easy-to-implement solution for disbursing funds to payees globally. Integrating the solution involves two steps:

1. Payee registration – implemented with client branded web pages that are hosted by Payoneer.

2. Submitting payment instructions to Payoneer, via one of two supported interfaces: Automated interface: HTTPS Request/Response interface available for

automating data submission and to retrieving reports. The APIs are described in section 4 of this document. Credentials for submitting API calls to sandbox and production environments will be provided during the client account setup process.

Manual interface: Payoneer Administration Console provides a convenient interface for manual data submission and access to reports. The Payments tab supports initiating single payments and uploading payment batch files to Payoneer.

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      5 

1.2 The Process

Data and Fund Exchanges

The workflow schematic below illustrates the data and fund exchanges performed for onboarding a payee and initiating a payments to the payee:

1. Payee Registration: A payee signs up at a branded page hosted by Payoneer. The client redirects payees to the Payoneer site, and upon completion of the sign up, the payee is redirected back to the client’s website or any other provided URL.

Payee sign-up can be implemented in an iFrame window.

2. Account Approval: Payoneer approves the account, and sends an account approval email to the payee. The payee receives communication from Payoneer based on the payout options that they selected during account enrollment/registration:

o Physical MasterCard Card: If the payee chose a physical card, Payoneer delivers the card directly to the payee’s address on file.

o Virtual MasterCard Card: If the payee chose a virtual card, Payoneer sends an additional email to the payee instructing them to login to their Payoneer “My Account” in order to access the 16-digit MasterCard number, expiration date, and CVV number (this option is available per client setup).

o iACH/Paper Check: If the payee chose the bank transfer or Paper Check option, there is no additional communication from Payoneer to the payee until account loading occurs.

3. Funds Transfer: Client transfers funding for the payout to Payoneer's bank account.

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      6 

4. Payment Instructions: Client sends payout instructions to Payoneer. These instructions are sent via the API or by uploading a mass payment file via the Payoneer Administration Console.

5. Email Funding Notification: Payoneer sends an email with an account load confirmation request to the payee.

6. Account Load: Payoneer loads the account.

Payoneer provides clients with reporting interfaces for sharing data, payment and status information at all stages of the workflow. Reporting is available through the following interfaces:

Payoneer Web-based reports. E-mail reports and notifications that are sent on a daily or monthly basis.

1.3 Communication Security To ensure communication safety and message integrity, Payoneer's platform implements a range of standard and proprietary security measures. Some of these include:

Validation of the Originating IP Address: Originating IP addresses of all client communications are validated against a list of confirmed IPs pre-defined for each client account (used for all applications).

API Permission System: Clients are permitted to use only the relevant API functions in accordance with their contract with Payoneer.

Unauthorized API Calls: No unauthorized API calls are allowed and all calls are logged.

SSL-Protected Communications: Electronic communications are performed through an SSL-protected channel.

TLS1.2 required: Client machines submitting API calls to Payoneer must support the TLS1.2 protocol.

Client Authentication with SSL certificates installed on the client’s servers that call the Payoneer API.

Password Protected Communications: API calls are authenticated with usernames and passwords assigned to clients at the time of account setup.

Using HTTP POST: Due to the potential risk of “Get” data being captured during communication-hops (e.g. DNS, routers) along the route.

Optionally enable reverse DNS for your domain.

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      7 

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

Sandbox credentials will be sent by Payoneer’s integration Department via email.

To access the Sandbox test environment, Clients must use a unique set of URLs. The credentials for Sandbox and Production environments are different. This means that the move from Sandbox to Production involves changing the base URLs and Credentials.

The API URL is as follows: https://api.sandbox.payoneer.com/payouts/HttpApi/Api.aspx?parameters 

The Client Admin Console URL is as follows: https://partners.sandbox.payoneer.com/ 

Payoneer will provide the production API URL along with the Production account credentials.

1.5 Common Calling Convention and Authentication All API requests share the following parameters:

Parameter Description Data Type Required

mname Method name Alphanumeric Yes

p1 Client Username

Client’s account username assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

p2 Client Password

Client’s unique password assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

p3 Client ID

Client’s unique ID assigned by Payoneer. Alphanumeric Yes

Sample Request Structure

curl -X POST https://api.sandbox.payoneer.com/Payouts/HttpApi/API.aspx -H "Content-Type: application/x-www-form-urlencoded" –d 'mname=XXX&p1={{ClientUserName}}&p2={{ClientPassword}}&p3={{ClientID}}'

Refer to Field Validations in Appendix C

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      8 

Common Error Codes

Authentication/Authorization

000FFF0 API function not allowed by client.

A00B556F Unauthorized access or invalid parameters. Please check IP address and parameters.

4B501FF5 Cannot find command or wrong method name.

Format Errors

001 Field format is invalid or is not supported.

Global Errors

002 Internal error.

003 Internal error.

005 Internal error.

006 Internal Error

008 Internal error.

PE1010 Unauthorized action.

099 Unauthorized access/Internal error.

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      9 

2 Onboarding Payees

2.1 Payee Sign-up Request a unique URL to the payee sign-up page that is generated by Payoneer specifically for each sign-up session.

Request Parameters

Parameter Description Data Type Required

mname Must be “GetToken” Alphanumeric Yes

p1 Client Username

Client’s account username assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

p2 Client Password

Client’s unique password assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

p3 Client ID

Client’s unique ID assigned by Payoneer. Alphanumeric Yes

p4 Client Payee ID

Payee’s Unique ID as used within the client’s system.

Alphanumeric No special characters

Yes

p5 Session ID

Payee session ID on the client’s Website. If provided, Payoneer sends it back upon process completion (IPCN).

Alphanumeric No

p6 Redirect URL

URL used by Payoneer for redirecting the payee back after completion of the sign-up process. Note that localhost is invalid

Alphanumeric No

p8 Redirect Time

The delay in seconds between the confirmation pages to the redirection to the client’s URL at the end of the account application. Default is 10 seconds.

Numeric No

p10 XML Response

Creates a XML response with the token URL.

String “True” – XML “False” – no XML

No

p11 Payout Methods Lists

List of allowed payout-methods for payees to choose from. The list is separated by commas. By default all payout-methods are presented to payees.

Alphanumeric Allowed payouts methods (non-case sensitive) : PrepaidCard iACH PaperCheck

No

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      10 

Parameter Description Data Type Required

p12 Registration Mode

Registration mode. Acceptable value are:

“Regular” – the default value. Exposes extended services such as Payoneer’s “MyAccount” application.

“Express” - supported only for iACH accounts. “Express” prompts the payee to fill in minimal details to receive payment, but does not include the extended services provided by “Regular” mode

“alreadyhaveanaccount” – causes the payee to be redirected to the “Payoneer already have an account” dialog box

Allowed values –

“Regular” “Express” “alreadyhaveanaccount”

No

Following payee registration, keeps the option for the payee to redirect to Payoneer using the same API call.

Sample Request

curl -X POST https://api.sandbox.payoneer.com/Payouts/HttpApi/API.aspx -H "Content-Type: application/x-www-form-urlencoded" –d 'mname=GetToken&p1={{ClientUserName}}&p2={{ClientPassword}}&p3={{ClientID}}&p4=ClientPayeeID'

The request returns a unique URL for a payee to access Payoneer’s sign-up page

Sample Successful XML Response

The response contains the unique URL for the payee sign-up page. The payee is then redirected to this URL for completion of the registration process.

<?xml version="1.0" encoding="UTF-8" ?> <PayoneerToken> <Token>http://payouts.payoneer.com/partners/lp.aspx?token=XXXAAAB</Token> </PayoneerToken>

This URL is valid for a single payee registration.

To setup landing site language, please refer to set language in Appendix D.

Sample Error Response

<PayoneerResponse> <Code>001</Code>

<Description> Field format is invalid or not supported</Description> </PayoneerResponse>

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      11 

2.2 Payee Sign-up/Auto Population Request a unique URL to the payee sign-up page that is generated by Payoneer specifically for each sign-up session. The request includes an XML parameter for auto populating data elements in the sign-up page.

Request Parameters

The payee sign-up page URL that is returned is unique and is generated by Payoneer specifically for each sign-up session.

Sample Request

curl -X POST https://api.sandbox.payoneer.com/Payouts/HttpApi/API.aspx -H "Content-Type: application/x-www-form-urlencoded" –d 'mname=GetTokenXML&p1={{ClientUserName}}&p2={{ClientPassword}}&p3={{ClientID}} &xml=<?xml version="1.0" encoding="utf-8"?> <PayoneerDetails>

<Details> <apuid>ClientPayeeID</apuid> <sessionid/> <redirect>http://www.ClientWebsite.com/</redirect> <redirectTime>2</redirectTime> <PayeeType>1</PayeeType> <PayoutMethodList>PrepaidCard</PayoutMethodList> <RegMode>regular</RegMode> <BlockType>0</BlockType>

</Details> <PersonalDetails>

Parameter Description Data Type Required

mname Must be “GetTokenXML” Alphanumeric Yes

p1 Client Username

Client’s account username assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

p2 Client Password

Client’s unique password assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

p3 Client ID

Client’s unique ID assigned by Payoneer. Alphanumeric Yes

Xml Client’s Unique ID assigned by Payoneer. Alphanumeric XML String Format

Yes

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      12 

<firstName>Dimitr</firstName> <lastName>ilkov</lastName> <country/> <address1/> <city/> <zipCode/> <dateOfBirth/> <phone/> <email>[email protected]</email> </PersonalDetails>

</PayoneerDetails>'

XML Parameters

Parameter Description Data Type

apuid Client Payee ID

Payee’s Unique ID as used within the client’s system.

Alphanumeric No special characters

sessionid Session ID

[Optional] Payee session ID on the client’s Website. If provided, Payoneer sends it back upon process completion.

Alphanumeric

redirect Redirect URL

[Optional] URL used by Payoneer for redirecting the payee back after completion of the sign-up process. Note that localhost is invalid.

Alphanumeric

redirectTime Redirect Time

[Optional] The delay in seconds between the confirmation pages for redirection to the client’s URL at the end of the card application. Default is 10 seconds.

Numeric

BlockType Block Type

[Optional] Field blocking prevents the end-user from being able to modify the specified fields. The level of field blocking in the auto-population option: 0 - no blocking (all fields can be changed – default) 1 - block all fields 2 - block address fields, Phone number 3 - block name fields/company legal name blocked 4 – block email address 5 - block name/company, legal name, address, & email fields 6 – block DOB. 7 – block all name /(company name, contact name) fields 8 – block all names/(company name, contact name) &address & email fields

Numeric 0-8

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      13 

Parameter Description Data Type

PayeeType

Payee Type

[Optional] 1 – Individual 2 – Company

Numeric

1-2

CompanyBusinessLegalType Company Business Legal Type

[Optional] 1 – Public Corporation (Co/Corp) 2 -- Private Corporation 3 -- Sole Proprietorship 4 – Limited Liability Company (LLC) 5 – Limited Liability Partnership (LLP) 6 – Limited Company (Ltd) 7 – Incorporation (Inc) 8 – Non Profit Organization

Numeric

1-8

CompanyName Company Name

[Optional] Used for autofill purposes. Alphanumeric

CompanyURL Company URL

[Optional] Used for autofill purposes. Alphanumeric

IncorporatedCountry Incorporated Country

[Optional] Used for autofill purposes. Alphanumeric

PayoutMethodList Payout Methods Lists

[Optional] List of allowed payout-methods for payees to choose from. The list is separated by commas. By default all payout-methods are presented to payees.

Alphanumeric Allowed payouts methods (non-case sensitive) – PrepaidCard iACH PaperCheck

RegMode Registration Mode

[Optional] “Express” registration mode is supported only for iACH accounts. “Express” prompts the payee to fill in minimal details to receive payment. “Regular” registration exposes extended services such as Payoneer’s “MyAccount” application. “Regular” is the default [Optional] “alreadyhaveanaccount” – causes the payee to be redirected to the “Payoneer already have an account” dialog box

Allowed iACH methods – Regular Express

or

“alreadyhaveanaccount”

PersonalDetails Section Tag

firstName Client Payee First Name

[Optional] Used for autofill purposes. Alphanumeric

lastName Client Payee Last Name

[Optional] Used for autofill purposes. Alphanumeric

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      14 

Parameter Description Data Type

dateOfBirth Client Payee Birth Date

[Optional] Used for autofill purposes. Must be parsed correctly in MMDDYYYY format.

Numeric

address1 Client Payee Address

[Optional] Used for autofill purposes. Alphanumeric 30 Characters

address2 Client Payee Secondary Address

[Optional] Used for autofill purposes. Alphanumeric 30 Characters

city Client Payee City

[Optional] Used for autofill purposes. Alphanumeric

country Client Payee Country

[Optional] Used for autofill purposes (2 letters, in accordance with ISO 3166-2).

Alphanumeric ISO2 code

state Client Payee State

[Optional] Used for autofill purposes. State code (2 letters, in accordance with ISO 3166-2)

Alphanumeric State code

zipCode Client Payee Zip

[Optional] Used for autofill purposes. Alphanumeric

mobile Client Payee Mobile Phone

[Optional] Used for autofill purposes. Alphanumeric

Phone Client Payee Phone

[Optional] Used for autofill purposes Alphanumeric

email [Optional] Used for autofill purposes. Alphanumeric

BankAccountDetails Section tag

BankName [Optional] Used for autofill purposes. Alphanumeric

AccountName [Optional] Used for autofill purposes. Alphanumeric

SWIFTSwift / BIC [Optional] Used for autofill purposes. Alphanumeric

IBAN [Optional] Used for autofill purposes. Alphanumeric

AccountNumber [Optional] Used for autofill purposes. Alphanumeric

BankNumber [Optional] Used for autofill purposes. Alphanumeric

BankCode [Optional] Used for autofill purposes. Alphanumeric

AccountTaxNumber [Optional] Used for autofill purposes. Alphanumeric

BIC [Optional] Used for autofill purposes. Alphanumeric

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      15 

Parameter Description Data Type

BranchCode [Optional] Used for autofill purposes. Numeric

BSB [Optional] Used for autofill purposes. Alphanumeric

BranchName [Optional] Used for autofill purposes. Alphanumeric

IdNumber [Optional] Used for autofill purposes. Alphanumeric

Gender [Optional] Used for autofill purposes. Alphanumeric

Prov / State [Optional] Used for autofill purposes. Alphanumeric

PostalCode [Optional] Used for autofill purposes. Alphanumeric

Address [Optional] Used for autofill purposes. Alphanumeric

AccountType [Optional] Used for autofill purposes. Alphanumeric

AccountOwnerType [Optional] Used for autofill purposes. Alphanumeric

AccountNameEnglish [Optional] Used for autofill purposes. Alphabet

iACHPhoneNumber [Optional] Used for autofill purposes. Numeric

AccountNumberPrefix [Optional] Used for autofill purposes. Alphanumeric

Suffix [Optional] Used for autofill purposes. Alphanumeric

IncorporationNumber [Optional] Used for autofill purposes. Alphanumeric

DdateOfBirth [Optional] Used for autofill purposes. Must be parsed correctly in MMDDYYYY format

Numeric

FirstName [Optional] Used for autofill purposes. Alphabet

LastName [Optional] Used for autofill purposes. Alphabet

PatronymicName [Optional] Used for autofill purposes. Alphanumeric

SortCode [Optional] Used for autofill purposes. Alphanumeric

Routing [Optional] Used for autofill purposes. Alphanumeric

Fields under BankAccountDetails should be populated appropriately for the country and currency of the payee’s bank account.

Refer to Field Validations in Appendix C.

Following payee registration, keeps the option for the payee to redirect to Payoneer using the same API call.

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      16 

Sample Successful Response

The request returns an XML formatted string containing the unique URL to the payee sign-up page as well as information about the new account holder that is created.

<?xml version="1.0" encoding="UTF-8" ?> <PayoneerToken> <Token>http://payouts.payoneer.com/partners/lp.aspx?token=XXXAAAB</Token> </PayoneerToken>

This URL is valid for a single payee registration.

To setup landing site language, please refer to set language in Appendix D.

Sample Error Response

<PayoneerResponse> <Result><!-- See status code table below --> </Result>

<Description> describes the reason for rejecting the request --> </Description> </PayoneerResponse>

Error Codes

PE1005 No client ID received.

PE1006 No payee ID received.

PE1011 Required field is missing.

PE1023 Invalid ID type.

PE1028 Invalid currency.

FFA009A Auto populate XML contains invalid entries.

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      17 

3 Instant Process Completion Notifications An Instant Process Completion Notification (IPCN) is a call triggered from Payoneer’s system to a client’s system. Typically, such a call reports an event about which the client or payee wishes to receive notification.

To receive an IPCN, a specific setup (in accordance with IPCN type) is configured in Payoneer’s administration console.

If the call fails due to network timeout, Payoneer's server performs five additional attempts. If all six IPCN attempts fail, an e-mail notification is sent to a pre-defined e-mail address within the client’s organization.

Payoneer supports the IPCN notifications presented in the following sections.

3.1 Payment Method Registration Notifications

Card Registration Confirmation

This is performed after the payee completes the registration process for a prepaid card.

Example:

https://www.partnercompany.com/payoneer_confirmation.aspx?REG=true&payeeid={{apuid}}&sessionid={{sessionid}}&Payoneerid={{payoneerid}}

iACH Registration Confirmation

This is performed after the payee finishes the registration process for iACH.

Example:

https://www.partnercompany.com/payoneer_confirmation.aspx?iACHREG=true&payeeid={{apuid}}&sessionid={{sessionid}}&Payoneerid={{payoneerid}}

Paper Check Registration Confirmation

This is performed after the payee finishes the registration process for Paper Check.

Example:

https://www.partnercompany.com/payoneer_confirmation.aspx?PaperCheck=true&payeeid={{apuid}}&sessionid={{sessionid}}&Payoneerid={{payoneerid}}

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      18 

3.2 Payee Status Notifications

Approved

This occurs if Payoneer approves the payee application.

Example:

https://www.partnercompany.com/payoneer_confirmation.aspx?APPROVED=true&payeeid={{apuid}}&sessionid={{sessionid}}&Payoneerid={{payoneerid}}

Once Payoneer approves a payee application (see “IPCN Approved” above), the payee ID is active in the Payoneer system and the client can submit payments to the payee.

Decline

This occurs if Payoneer declines the payee application.

Example:

https://www.partnercompany.com/payoneer_confirmation.aspx?DECLINE=true&payeeid={{apuid}}&sessionid={{sessionid}}&Payoneerid={{payoneerid}}

apuid is the payee ID: This is the unique identifier that each client has for each payee.

Session ID: Is the p5 parameter sent in the signup API. It is not mandatory. Payoneer ID: This is an identifier used within the Payoneer system. It is not

mandatory.

3.3 Payment Notifications

Payment Request Accepted

This occurs once a payment request has been registered in Payoneer systems.

Example:

https://www.partnercompany.com/payoneer_confirmation.aspx?PAYMENT=true&payeeid={{apuid}}&PaymentId={{PayoneerPaymentId}}&PartnerPaymentId={{IntPaymentId}}

Card Loaded Confirmation

This occurs once the funds are loaded into the card.

Example:

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      19 

https://www.partnercompany.com/payoneer_confirmation.aspx?LOADCC=true&payeeid={{apuid}}&PayoneerPaymentId={{PaymentId}}&PartnerPaymentId={{IntPaymentId}}

Load Money to iACH

This occurs after funds have been sent to the iACH payee.

Example:

https://www.partnercompany.com/payoneer_confirmation.aspx?LOADiACH=true&payeeid={{apuid}}&PaymentId={{PaymentId}}&PartnerPaymentId={{IntPaymentId}}

Load Money to Paper Check

This occurs after funds have been sent to the Paper Check payee.

Example:

https://www.partnercompany.com/payoneer_confirmation.aspx?PaperCheck=true&payeeid={{apuid}}&PaymentId={{PaymentId}}&PartnerPaymentId={{IntPaymentId}}

Cancel Payment

This occurs: after a payment has been canceled.

Example:

https://www.partnercompany.com?CancelPayment=true&payeeid={{apuid}}&PaymentId={{PaymentId}}&PartnerPaymentId={{IntPaymentId}}

apuid: This is the payee ID, which is the unique identifier that each client has for each payee

PayoneerPaymentId: This is a unique payment identifier used within the Payoneer system.

IntPaymentId: This is a unique payment identifier used within the client’s system.

3.4 Additional IPCN Notifications

Account Funded

This occurs once client’s funds have been received (i.e. once the client’s balance in the Payoneer system is updated).

Example:

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      20 

https://www.partnercompany.com/payoneer_confirmation.aspx?BALANCE_UPDATED=true&Amount={{Amount}}&Balance={{Balance}}&FundingId={{FundingId}}&FundingTime={{FundingTime}}

Balance is the Client’s balance in Payoneer right after the funding action Fundingid is a unique identifier in Payoneer system of the specific funding action. FundingTime is the Date and time (EST) the funding registerd in Payoneer

systems.

Auto Payee Creation

This occurs once Payoneer creates a payee automatically for the client.

Example:

https://www.partnercompany.com/payoneer_confirmation.aspx?AUTOPAYEECREATION=true&payeeid={{apuid}}&PaymentId={{PaymentId}}

Email As Payee: If the client is enabled in the Payoneer systems for the “Email as payee” service, then the client can submit a payment to a payee (via the PerformPayoutPayment API call) by specifying their email address in the Payoneer system as “PayeeID”. If the payee is identified by the Payoneer system (according to their email), the Payoneer system will automatically create a payee ID named according to the payee’s email for the requesting client. From then on, the “email” is the payee ID.

Customer Details Edited

This occurs once the payee profile is edited.

Example:

https://www.partnercompany.com/payoneer_confirmation.aspx?CustomerDetailsEdited=true&payeeid={{apuid}}&sessionid={{sessionid}}&Payoneerid={{payoneerid}}

Payee Bank Account Details Change Notification

This occurs once the payee changes his Bank account information.

Example:

https://www.partnercompany.com/payoneer_confirmation.aspx?CustomerDetailsEdited=true&payeeid={{apuid}}

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      21 

Reuse Payee ID

This occurs once the payee ID is released by Payoneer and should open the option for the payee to re-register for Payoneer account.

Example:

https://www.partnercompany.com/payoneer_confirmation.aspx?ReusePayeeID=true&payeeid={{apuid}}

Bank Transfer Payment Failed

This occurs when an instruction requesting a bank transfer fails. The IPCN returns the unique payment ID and a reason code describing the reason for failure.

Example:

https://www.partnercompany.com/payoneer_confirmation.aspx?BankTranferPaymentFailed=true&payeeid={{apuid}}&PartnerPaymentId={{IntPaymentId}}&PayoneerPaymentId={{PaymentId}}&ReasonCode={{ReasonCode}}&ReasonDescription={{ReasonDescription}}

Reason Codes:

Reason Code Reason Description

58 Payout rejected - Invalid Beneficiary Details

217 Payout rejected - Account Closed

206 Payout rejected - Invalid account number

61 Payout rejected - Bank cannot process

208 Payout rejected - Invalid routing number

209 Payout rejected - Invalid account name

210 Payout rejected - Invalid Swift Code

207 Payout rejected - Account in wrong currency

211 Payout rejected - Invalid Bank Code

113 Payout rejected - Unsuccessful (Unknown)

213 Payout rejected - Invalid Branch Code

215 Payout rejected - Wrong Account Type

59 Payout rejected - Recall requested by Remitter

60 Payout rejected - Regulatory reason

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      22 

4 The Payoneer API The following sections present the various functions of the Payoneer API. The API is intended for developers who need to drive payments directly to the Payoneer platform or query the platform for information about their payees and payments.

4.1 Echo Return the status of the API and payout services (Heart Beat).

Request Parameters

Field Description Data Type Required

mname Must be “Echo” Alphanumeric Yes

p1 Client Username

Client’s account username assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

p2 Client Password

Client’s unique password assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

p3 Client ID

Client’s unique ID assigned by Payoneer.

Alphanumeric Yes

Sample Request

curl -X POST https://api.sandbox.payoneer.com/Payouts/HttpApi/API.aspx -H "Content-Type: application/x-www-form-urlencoded" -d 'mname=Echo&p1={{ClientUserName}}&p2={{ClientPassword}}&p3={{ClientID}}

Sample Response

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <PayoneerResponse> <Status>0</Status> <Description>OK</Description> </PayoneerResponse>

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      23 

Status Codes

000 Echo OK - All systems are up.

4.2 GetVersion Return the API version (corresponding with the relevant integration guide)

Request Parameters

Field Description Data Type Required

mname Must be “GetVersion” Alphanumeric Yes

p1 Client Username

Client’s account username assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

p2 Client Password

Client’s unique password assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

p3 Client ID

Client’s unique ID assigned by Payoneer.

Alphanumeric Yes

Sample Request

Sample Successful Response

4.3 Payment Order Submission Submit a payment request to Payoneer’s system. Prior to issuing payment instructions, the client’s account balance in Payoneer’s system must be credited to cover the instructions requested. Payout instruction submission will fail if the client’s account balance does not have sufficient funds to perform the payment instructions. In addition, the payee ID must be active. (The payee has successfully on-boarded Payoneer; see section 2)

curl -X POST https://api.sandbox.payoneer.com/payouts/httpapi/api.aspx -H "Content-Type: application/x-www-form-urlencoded" -d 'mname=GetVersion&p1={{ClientUserName}}&p2={{ClientPassword}}&p3={{ClientID}}

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <PayoneerResponse> <Version>4.6.7.0 </Version> </PayoneerResponse>

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      24 

Another option to submit payments is to create a batch file (XML, CSV, or Excel file format. Refer to Appendix A and B for information on the file format) and upload the file from the Payoneer Administration Console.

Request Parameters

Field Description Data Type Required

mname Must be “PerformPayoutPayment” Alphanumeric Yes

p1 Client Username

Client’s account username assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

p2 Client Password

Client’s unique password assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

p3 Client ID

Client’s unique ID assigned by Payoneer. Alphanumeric Yes

p4 Program ID

Program code in the Payoneer system as supplied during the client’s account setup.

Alphanumeric Yes

p5 Internal Payment ID

Unique payment ID assigned by the client. It can also serve as a “reference ID” in the client’s system.

This field is NOT case sensitive.

Alphanumeric No special characters

Yes

p6 Internal Payee ID

Payee ID as set in the client’s system. If the client is enabled in the Payoneer systems for the “Email as payee” service then a payee’s email can be used (as “Internal payee ID”), if the specified email belongs to a Payoneer account-holder and the payment data is valid. In such a case, the specified email will be automatically assigned as “payee” and can be used as “internal payee ID” in any other API call from then on.

Alphanumeric No special characters

Yes

p7 Amount

Payment amount in program currency. Fees charged to payees are deducted from this amount. Payments lower than the minimum payment amount will be rejected.

Two decimal places 0.00

Yes

p8 Description

Payment description. Alphanumeric Yes

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      25 

Field Description Data Type Required

p9 Payment Date

Date of payment (EST), Normally, the specified date is ignored, and the payment is executed immediately upon payment submission. A client can be configured in the Payoneer system for “Payments scheduling”. Using this configuration (which is inactive by default), the payment is executed only at the time specified by the “Payment date” parameter.

Numeric (MM/DD/YYYY HH:MM:SS)

Yes

P11 Group ID

Field used for group payments (allows attribution of payment to a department or expense group).

Alphanumeric No

Currency The ISO3 Currency code. Must match the program’s currency. Default is USD (3 letters, in accordance with ISO 4217)

Alphabet No

The Internal Payment ID field (p5) must be unique for the payment instruction. If a payment fails for any reason, the same payment ID (field p5) should be used for reprocessing the same request.

Sample Request

Sample Successful Response

curl -X POST https://api.sandbox.payoneer.com/Payouts/HttpApi/API.aspx -H "Content-Type: application/x-www-form-urlencoded" -d 'mname=PerformPayoutPayment&p1={{ClientUserName}}&p2={{ClientPassword}}&p3={{ClientID}}&p4={{ClientProgramID}}&p5=IntPaymentID&p6=ClientPayeeID&p7=10.00&p8=PaymentTest&p9=09/01/2016 10:56:00'

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <PerformPayoutPayment> <Description><!-- If Status is not 000, describes the reason for rejecting the request --> </Description> <PaymentID><!-- A unique reference code for the payment performed --> </PaymentID> <Status><!-- See status code table below --></Status> <PayoneerID><!-- The unique Payee ID in the Payoneer system --> </PayoneerID> </PerformPayoutPayment>

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      26 

Status Codes

000 Processed successfully.

002 Payee does not exist.

003 Insufficient funds

004 Payment ID {{Internal Payment ID}} already exists.

011 Funding not enabled.

010 Payee is inactive.

030 Currency Mismatch

001m Minimum/ maximum loading amount / Amount to load is less or equal to zero.

002b Internal error.

002t Internal error.

002em Payee does not exist.

006n Internal error.

007d Internal error.

007f Internal error.

007g Internal error.

PE1028 Invalid currency.

4.4 Get Payment Status Report the status of a payment that was previously sent to the Payoneer system.

Request Parameters

Field Description Data Type Required

mname Must be “GetPaymentStatus” Alphanumeric Yes

p1 Client username

Client’s account username assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

p2 Client password

Client’s unique password assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      27 

Field Description Data Type Required

p3 Client ID

Client’s unique ID assigned by Payoneer. Alphanumeric Yes

p4 Internal Payee ID

Payee ID as set in the Client’s system. Alphanumeric No special characters

Yes

p5 Internal Payment ID

Unique payment ID assigned by the client.

Alphanumeric No special characters

Yes

Sample Request

Sample Successful Response

Status Codes

000 OK (Request accepted).

PE1011 Required field is missing.

PE1026 Invalid Payment ID or Payee ID.

curl -X POST https://api.sandbox.payoneer.com/Payouts/HttpApi/API.aspx -H "Content-Type: application/x-www-form-urlencoded" -d 'mname=GetPaymentStatus&p1={{ClientUserName}}&p2={{ClientPassword}}&p3={{ClientID}}&p4=ClientPayeeID&p5=IntPaymentID'

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <GetPaymentStatus>

<PaymentId><!—The internal payment Id --></PaymentId> <Result><!-- See status code table below --> </Result> <Description><!-- If Status is not 000, describes the reason for rejecting the request --> </Description> <PaymentDate> <!—Time the payment sent to Payoneer --> </PaymentDate>

<Amount> </Amount> <Status> <!-- See Payment status code table --> </Status> <LoadDate> <!—Time the payment loaded --> </LoadDate> <Curr></Curr>

</GetPaymentStatus >

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      28 

Payment Statuses

Pending Approval

Cancelled

Refund

Payment completed

Funded

Pending Load

Settling

Error

4.5 Query Account Balance Method Return the client’s available account balance.

Request Parameters

Field Description Data Type Required

mname Must be “GetAccountDetails” Alphanumeric Yes

p1 Client Username

Client’s account username assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

p2 Client Password

Client’s unique password assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

p3 Client ID

Client’s unique ID assigned by Payoneer. Alphanumeric Yes

Sample Request

Sample Successful Response

curl -X POST https://api.sandbox.payoneer.com/payouts/HttpApi/Api.aspx -H "Content-Type: application/x-www-form-urlencoded" -d ‘mname=GetAccountDetails&p1={{ClientUserName}}&p2={{ClientPassword}}&p3={{ClientID}} ‘

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      29 

Status Codes

000 OK (Request accepted).

4.6 Get Payee Details Return details about the requested payee and its status at Payoneer.

Request Parameters

Field Description Data Type Required

mname Must be “GetPayeeDetails” Alphanumeric Yes

p1 Client Username

Client’s account username assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

p2 Client Password

Client’s unique password assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

p3 Client ID

Client’s unique ID assigned by Payoneer.

Alphanumeric Yes

p4 Payee ID

Client’s payee ID as it appears in the Payoneer system.

Alphanumeric No special characters

Yes

Sample Request

Sample Successful Response

<GetAccountDetails> <FeesDue><!-- Fees due by client to Payoneer --></FeesDue> <AccountBalance>(Balance remaining in the Client’s Account for payments)</AccountBalance> <Curr> (optional – currency other than USD - Program currency ) </Curr>

</GetAccountDetails>

curl -X POST https://api.sandbox.payoneer.com/Payouts/HttpApi/API.aspx -H "Content-Type: application/x-www-form-urlencoded" -d 'mname=GetPayeeDetails&p1={{ClientUserName}}&p2={{ClientPassword}}&p3={{ClientID}}&p4=ClientPayeeID '

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <GetPayeeDetails> <Payee>

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      30 

Status Codes

000 OK (Request accepted).

002 Payee does not exist.

Payee Statuses Inactive Account cannot be loaded by client.

Active Account can be loaded.

<FirstName> (if company contains Company legal Name) </FirstName> <LastName> (if company contains Full Name of Payee) </LastName> <Address1></Address1> <Address2></Address2> <City></City> <State></State> <Zip></Zip> <Country></Country> <Email></Email> <Phone></Phone> <Mobile></Mobile> <PayeeStatus></PayeeStatus> <RegDate></RegDate> <PayOutMethod> (Prepaid Card/iACH/PaperCheck/PayoneerAccount) </PayOutMethod> <Cards> (if PayOutMethod is Prepaid Card ) <Card> (for active card) <CardID> </CardID> <ActivationStatus> </ActivationStatus> <CardShipDate> </CardShipDate> (optional) (not returned when card is not approved) <CardStatus> </CardStatus> </Card> </Cards> <PayoutMethodDetails> (If PayOutMethod is Payoneer Account) <ActivationStatus></ActivationStatus> </PayoutMethodDetails> </Payee> <CompanyDetails> <CompanyName></CompanyName> </CompanyDetails> </GetPayeeDetails>

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      31 

Payoneer Account Activation Statuses

Pending Approval

Not Activated

Activated

Cancelled

Card Activation Statuses

Not Issued, Pending Approval

Card Issued, Not Activated

Card Activated

Card Cancelled

4.7 Change Payee ID Change the ID of an existing payee (old) to a new one.

Request Parameters

Field Description Data Type Required

mname Must be “ChangePayeeID” Alphanumeric Yes

p1 Client Username

Client’s account username assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

p2 Client Password

Client’s unique password assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

p3 Client ID

Client’s unique ID assigned by Payoneer.

Alphanumeric Yes

p4 old Payee ID

Client’s payee ID as it appears in the Payoneer system.

Alphanumeric No special characters

Yes

P5 new Payee ID

New client’s payee ID to be set. Alphanumeric No special characters

Yes

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      32 

Sample Request

Sample Successful Response

Status Codes

000 Processed successfully.

003 New payee ID already exists.

PE1013 Payee ID is invalid.

4.8 Get Payees Report Return all payments made to payees, grouped by payment method.

API call limit is for a 1-month period.

Request Parameters

Field Description Data Type Required

mname Must be “GetPayeesReport” Alphanumeric Yes

p1 Client Username

Client’s account username assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

p2 Client Password

Client’s unique password assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

curl -X POST https://api.sandbox.payoneer.com/Payouts/HttpApi/API.aspx -H "Content-Type: application/x-www-form-urlencoded" -d 'mname=ChangePayeeID&p1={{ClientUserName}}&p2={{ClientPassword}}&p3={{ClientID}}&p4=OldClientPayeeID&p5=NewPayeeID'

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <ChangePayeeID>

<OldPayee><!—The payee ID that was changed --></OldPayee> <NewPayee><!—New Payee ID assigned --></NewPayee> <Result><!-- See code table --></Result> <Description><!—description of error --></Description>

</ChangePayeeID>

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      33 

Field Description Data Type Required

p3 Client ID

Client’s unique ID assigned by Payoneer. Alphanumeric Yes

p4 Report Type

Type of report to generate. Presently only XML reports are supported.

Integer (Enum) XML = 0

No

P5 Start Date

Date of payment from which search will be commenced.

Date MM/dd/yyyy

Yes

P6 End Date

Date of payment at which search will end. Date MM/dd/yyyy

Yes

Sample Request

Sample Successful Response

curl -X POST https://api.sandbox.payoneer.com/Payouts/HttpApi/API.aspx -H "Content-Type: application/x-www-form-urlencoded" -d 'mname=GetPayeesReport&p1={{ClientUserName}}&p2={{ClientPassword}}&p3={{ClientID}}&p5=08/01/2016 &p6=09/01/2016'

<?xml version="1.0" encoding="utf-8" standalone="no"?> <PayoneerPayees> <Prepaid> OR <BankAccout> OR <iACH> OR <PaperCheck> OR <PayoneerAccount> (following are listed all the payees that have registered for Prepaid) <Payee> <PayeeId></PayeeId> <Name> </Name> <Email> </Email> <RegistrationDate> </RegistrationDate> <Status> </Status> <TotalAmount></TotalAmount> (all of this payee’s payments) <Payments> <Payment> <Date> </Date> <PaymentID>(Client’s Payment ID) </PaymentID> <PayoneerReferenceID>(Payoneer Payment ID)</PayoneerReferenceID> <Amount> </Amount> <Curr> </Curr> <Status> </Status> <Description> </Description> </Payment> </Payments>

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      34 

Status Codes

PE1017 Invalid date range.

4.9 Get Single Payee Report Return all payments made to a specified payee.

Request Parameters

Field Description Data Type Required

mname Must be “GetSinglePayeeReport” Alphanumeric Yes

p1 Client Username

Client’s account username assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

p2 Client Password

Client’s unique password assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

p3 Client ID

Client’s unique ID assigned by Payoneer. Alphanumeric Yes

p4 Payee ID

Client’s payee ID as it appears in the Payoneer system.

Alphanumeric No special characters

Yes

Sample Request

Sample Successful Response

</Payee> </Prepaid> OR </BankAccout> OR </iACH> OR </PaperCheck> OR </PayoneerAccount> </PayoneerPayees>

curl -X POST https://api.sandbox.payoneer.com/Payouts/HttpApi/API.aspx -H "Content-Type: application/x-www-form-urlencoded" -d 'mname=GetSinglePayeeReport&p1={{ClientUserName}}&p2={{ClientPassword}}&p3={{ClientID}}&p4=ClientPayeeID '

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <PayoneerPayees> <Prepaid> OR <BankAccout> OR <iACH> OR <PaperCheck> OR <PayoneerAccount> <Payee>

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      35 

Status Codes

PE1013 Payee ID is invalid.

4.10 Get Unclaimed Payments XML Return a list of all payments that are unclaimed in XML format.

Request Parameters

Field Description Data Type Required

mname Must be “GetUnclaimedPaymentsXML” Alphanumeric Yes

p1 Client Username

Client’s account username assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

p2 Client Password

Client’s unique password assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

p3 Client ID

Client’s unique ID assigned by Payoneer. Alphanumeric Yes

<Name> </Name> <Email> </Email> <RegistrationDate> </RegistrationDate> <Status> </Status> <TotalAmount> </TotalAmount> <Payments> <Payment> <Date> </Date> <PaymentID>(Client Payment ID) </PaymentID> > <PayoneerReferenceID>(Payoneer Payment ID)</PayoneerReferenceID> <Amount> </Amount> <Curr></Curr> <Status> </Status> <Description> </Description> </Payment> </Payments> </Payee> </Prepaid> OR </BankAccout> OR </iACH> OR </PaperCheck> OR </PayoneerAccount> </PayoneerPayees>

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      36 

Sample Request

Sample Successful Response

4.11 Get Unclaimed Payments CSV Return a list of all payments that are unclaimed in CSV format.

Request Parameters

Field Description Data Type Required

mname Must be “GetUnclaimedPaymentsCSV” Alphanumeric Yes

curl -X POST https://api.sandbox.payoneer.com/payouts/HttpApi/Api.aspx -H "Content-Type: application/x-www-form-urlencoded" -d "mname=GetUnclaimedPaymentsXML&p1={{ClientUserName}}&p2={{ClientPassword}}&p3={{ClientID}} ‘

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <GetUnclaimedPayments> <Payment> <IntPayeeId> (--as assigned by client --) </IntPayeeId> <IntPaymentId> (--as assigned by client --) </IntPaymentId> <PayoneerPaymentId> (--internal payoneer reference --) </PayoneerPaymentId> <Amount> (-- as calculated in payment --) </Amount> <!--payee details as provided by payee: --> <FirstName> </FirstName> <LastName> </LastName> <Address1> </Address1> <Address2> </Address2> <City> </City> <State> </State> <Zip> </Zip> <Country> (--2 letter code --) </Country> <Email> </Email> <Phone> </Phone> <Mobile> </Mobile> <PayOutMethod>(PrepaidCard /iACH/PaperCheck/PayoneerAccount)</PayOutMethod> <PaymentDate> </PaymentDate> <Description> (--as provided in payment --) </Description> <Curr> </Curr> </Payment> </GetUnclaimedPayments>

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      37 

p1 Client Username

Client’s account username assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

p2 Client Password

Client’s unique password assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

p3 Client ID

Client’s unique ID assigned by Payoneer. Alphanumeric Yes

Sample Request

Successful Response

A comma separated string in which each row contains the following information:

IntPayeeId is the payee ID as set in the client's system IntPaymentId is the payment ID as set in the client's system

4.12 Cancel Payment Cancel a payment that has not yet been processed and loaded to an account.

Request Parameters

Field Description Data Type Required

mname Must be “CancelPayment” Alphanumeric Yes

p1 Client Username

Client’s account username assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

p2 Client Password

Client’s unique password assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

p3 Client ID

Client’s unique ID assigned by Payoneer.

Alphanumeric Yes

curl -X POST https://api.sandbox.payoneer.com/payouts/HttpApi/Api.aspx -H "Content-Type: application/x-www-form-urlencoded" -d "mname=GetUnclaimedPaymentsCSV&p1={{ClientUserName}}&p2={{ClientPassword}}&p3={{ClientID}} ‘

IntPayeeId*, IntPaymentId*, PaymentId, Amount, FirstName, LastName, Address1, Address2, City, State, Zip, Country, Email, Phone, Mobile, PayOutMethod, PaymentDate, Description, Currency 

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      38 

p4 Internal Payment ID

Client’s payment ID as assigned upon payment.

Alphanumeric Yes

Sample Request

Sample Successful Response

Status Codes

000 Payment cancelled successfully.

002 Payment has already been processed.

003 Payment has already been cancelled / rejected.

004 Failed to cancel payment.

PE1026 Invalid payment ID.

4.13 Move Payee Program Move payees and their payments to an alternate program. Used by clients with two or more programs.

Cannot move payees between programs with different currencies.

Request Parameters

Field Description Data Type Required

mname Must be “MovePayeeProgram” Alphanumeric Yes

curl -X POST https://api.sandbox.payoneer.com/payouts/HttpApi/Api.aspx -H "Content-Type: application/x-www-form-urlencoded" -d 'mname=CancelPayment&p1={{ClientUserName}}&p2={{ClientPassword}}&p3={{ClientID}}&p4=IntPayemntID'

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <CancelPayment> <PaymentID> (-- of the cancelled payment --) </PaymentID> <Result> (-- 000 means success, otherwise see table --) </Result> <Amount> (-- amount of the cancelled payment --) </Amount> <Curr> (-- currency of cancelled payment --) </Curr> <Description> (-- description of the cancelled payment --) </Description> </CancelPayment>

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      39 

p1 Client Username

Client’s account username assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

p2 Client Password

Client’s unique password assigned by Payoneer (provided upon setup of the client’s account profile).

Alphanumeric Yes

p3 Client ID

Client’s unique ID assigned by Payoneer. Alphanumeric

Yes

P4 Client Username

Client’s account username assigned by Payoneer (the client to which the payee will be moved).

Alphanumeric Yes

P5 Client Password

Client’s unique password assigned by Payoneer (the client to which the payee will be moved).

Alphanumeric Yes

P6 Client ID

Client’s account ID number in the Payoneer system (the client to which the payee will be moved).

Alphanumeric

Yes

P7 Payee ID

Client’s payee ID as it appears in the Payoneer system (the payee to be moved).

Alphanumeric Yes

Sample Request

Sample Successful Response

curl -X POST https://api.sandbox.payoneer.com/payouts/HttpApi/Api.aspx -H "Content-Type: application/x-www-form-urlencoded" -d ‘mname=movepayeeprogram&p1={{ClientUserName}}&p2={{ClientPassword}}&p3={{ClientID}}&p4={{Client2UserName}}&p5={Client2Password}}&p6={{Client2ID}}&p7= ClientPayeeID ‘

<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <MovePayeeProgram> <oldPartnerId> (— The original partner ID--) </oldPartnerId> <newPartnerId> (— New partner ID to assign to --) </newPartnerId> <partnerPayeeId> (-- Partner Payee ID to be change --) </partnerPayeeId> <Result> (-- See code table --) </Result> <Description> (-- description of error --) </Description> </MovePayeeProgram>

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      40 

Status Codes

000 Processed successfully.

002 No active payout method for the card holder.

PE1013 Payee ID is invalid.

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      41 

Appendix A – XML File Format for Payoneer Mass Payment Each payment is represented by a PayoutPayment section. The parameters in each section are as follows:

Description Parameter

Date of payment (EST), in "MM/DD/YYYY" format. Normally, the specified date is ignored, and the payment is executed immediately upon payment submission. A client can be configured in the Payoneer system for “Payments scheduling”. Using this configuration (which is inactive by default), the payment is executed only at the time specified by the “Payment date” parameter.

Payment date 1

The ID this payee has in your system. Payee ID 2

As appears in your internal system. Must be unique per payment. Int. Payment ID 3

Amount to transfer to the payee. Amount 4

Payment currency. Must be Program’s currency Currency 5

A short description of the payment. Description 6

[Optional] Optional field used for grouping payments (allows attribution of payment to a department or expense group)

Group ID 7

The following is a sample XML file.

<?xml version="1.0" encoding="utf-8" standalone="no"?> <PayoneerIn> <PayoutPayments> <PayoutPayment> <PaymentDate> <!--Date of payment MM/DD/YYYY--> </PaymentDate> <PayeeID> <!--ID of the payee --> </PayeeID> <IntPaymentID> <!--Client internal payment ID for this payment --> </IntPaymentID> <Amount> <!--Amount to pay --> </Amount> <Currency>USD<!--Currency of payment--></Currency> <Description> <!--description of the payment --> </Description> <GroupID> <!—Optional department for attribution of payment --> </ GroupID > </PayoutPayment> </PayoutPayments> <Totals> <Amount> <!-- aggregate sum of all payment amounts in batch --> </Amount> </Totals> </PayoneerIn>

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      42 

Appendix B – Payoneer Mass Payment CSV File Format A comma-delimited file (CSV) can be generated /imported from most spreadsheet applications, such as Excel, by clicking on “save as CSV”.

The CSV file includes seven columns:

The first column includes the unique payee ID. The second column includes the payment amounts for each payee. The third column includes the payment’s ISO3 currency code, which must be the

program’s currency. The fourth column includes the Payment ID, which is a unique ID number per

payment and cannot ever be repeated. The fifth column includes a description field, which is a free text field to enter a

description of the payment (e.g., “March commission payments”). The sixth column includes the payment date. The seventh column is an optional field used for grouping payments (It allows the

user to group payments by a department or an expense.)

Description Parameter

The ID this payee has in your system. Payee ID 1

Amount to transfer to the payee. Amount 2

Payment currency. Must be in program’s currency. Currency 3

This must be the same at the information appearing in the internal system. It must be unique per payment and cannot be repeated in the future.

Int. Payment ID 4

A short description of the payment. Description 5

Date of payment (EST), at "MM/DD/YYYY" format. Normally, the specified date is ignored, and the payment is executed immediately upon payment submission. A client can be configured in Payoneer system for “Payments scheduling”. Using this configuration (which is inactive by default), the payment will be executed only at the time specified by the “Payment date” parameter.

Payment date 6

[Optional] Optional field used for grouping payments (allows the user to group payments by a department or an expense).

Group ID 7

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      43 

The following is a sample CSV file formatted for Payoneer Mass Payments:

PayeeID1 1.25 USD IntPaymentID1 Test Payment for PayeeID1 1/1/2015

PayeeID2 1.25 USD IntPaymentID2 Test Payment for PayeeID2 1/1/2015

PayeeID3 2.55 USD IntPaymentID3 Test Payment for PayeeID3 1/1/2015

PayeeID4 3 USD IntPaymentID4 Test Payment for PayeeID4 1/1/2015

PayeeID5 1 USD IntPaymentID5 Test Payment for PayeeID5 1/1/2015

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      44 

Appendix C – Field Validations

Field Type Valid characters Min Length

Max Length

Address Alphanumeric, whitespaces, . , / , _ , - , ) , ( , \ , @ , # , ` , comma , * 30

Address 2 Alphanumeric, whitespaces, . , / , _ , - , ) , ( , \ , @ , # , ` , comma , * 30

Amount Digits, comma, . , - Two decimal places 0.00 100

City Letters, space 40

Country

Two letters, in compliance with ISO 3166-1 alpha-2 Country Code List.

Note that UK is specifically used for United-Kingdom 3

Date Can be parsed to a date using .net infrastructure 50

Description Alphanumeric, whitespaces, ( , ) ,/ , . , - , @ , % , ! , _ , : ,$, ", + , > 150

FirstName Letters, space, digits 2 26

intPaymentId Letters and digits, _ , - , ^ , ( , ) , @ , / , ! , #, space, $, ., : 50

LastName Letters, space, digits 2 26

ClientPayeeId Letters and digits, _ , - , ^ , @, ! , ? , ", . 50

Password Letters and digits, !, @, #, $, %, ^, & 7 12

PhoneNumber (, ), digits, - 6 11

RedirectURL Alphanumeric 255

RedirectTime Digits 1 3

SessionID Digits, letters, . ,!, - ,(space) 50

Group ID Alphanumeric 250

State Two Letters, U.S only state code, in accordance with ISO 3166-2 20

Zip Letters, digits, space, - 3 10

ID Type 1,2,3,4 1 1

SSN Digits, - 4 9

Driver License Number Letters, digits 30

National ID number Letters, digits 30

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      45 

Field Type Valid characters Min Length

Max Length

Passport ID Letters, digits 30

Name On Card Letters, digits, space, -, _ ,. 255

Company name Letters, space, digits, ( , ), . 50

Currency

3 letters, comply to ISO 4217 Currency Code List.

Must be Program’s currency 3

Incorporated Country

Two letters, in compliance with ISO 3166-1 alpha-2 Country Code List.

Note that UK is specifically used for United-Kingdom 3

Company URL

Valid url:  ^(https?://)?(([0‐9a‐zA‐Z_!~*'().&=+$%‐]+: )?[0‐9a‐zA‐Z_!~*'().&=+$%‐]+@)?(([0‐9]{1,3}\.){3}[0‐9]{1,3}|([0‐9a‐zA‐Z_!~*'()‐]+\.)*([0‐9a‐zA‐Z][0‐9a‐zA‐Z\‐]{0,61})?[0‐9a‐zA‐Z]\.[a‐zA‐Z]{2,})(:[0‐9]{1,5})?((/?)|(/[0‐9a‐zA‐Z_!~*'().;?:@&=+$,%#‐{}]+)+/?)$  255

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      46 

Appendix D – Setup Payoneer landing site language

1) Payoneer system has Auto-language detection - Landing page language detection is set according to the PC system language.

2) Another option is to add language parameter &langid={{LanguageCode}} to the token response back from Payoneer based on the language table below. Example for English:

LanguageCode LanguageName

1 English

3 Russian

4 Chinese

5 Turkish

6 Portuguese

7 Spanish

8 Hungarian

9 French

11 Greek

12 Malay

13 German

14 Japanese

15 Korean

16 Polish

18 Danish

19 Arabic

20 Italian

21 Vietnamese

24 Thai

25 Indonesian

https://payouts.payoneer.com/partners/lp.aspx?token=123&langid=1

Version 2.60

__________________________________________________________________________

© 2005-2016 by Payoneer Inc. This document contains proprietary and confidential information of Payoneer, Inc. and may not be disclosed or duplicated without the express written consent of Payoneer. Payoneer reserves the right to change this document at any time. 

 pg.      47 

Appendix E – Client’s Account Setup Process Payoneer sends the following information to the client’s Sandbox account:

Username & Password Client ID Program ID API URL Admin Console Interface URL Using the sandbox account credentials, the client is able to generate dynamic links and all other API calls, payment etc. in a testing environment that is distinct from the live production environment.

Once the client is ready for production, Payoneer will provide the production account information and request following details:

Once the production details are uploaded the client should inform Payoneer that the account is implemented.

Client’s IP addresses of all machines calling the API or using the Payoneer Administration Console. These addresses will be set in the monitoring system in order to verify the source of calls.

Test credentials and a link to login as a payee allowing Payoneer to register for an account and test the integration end-to-end.

IPCN (if in use) must be copied from the sandbox account to the production account.

Redirect URL: a default URL is required to redirect the payee after the payment method registration is finished. If a redirect URL is sent with the Payout URL as a parameter, Payoneer will redirect the payee to that URL and not to the default one.

Changes of IP addresses, if made.