Global Payments Made Easy - Payoneer · The Payoneer Sandbox Test Environment is a self-contained...
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.