Pay One Era Pi Guide
Pay One Era Pi Guide
Pay One Era Pi Guide
Payoneer Inc
Implementation Guide Payoneer Payout Services
http://www.payoneer.com
Page 1
Table of Contents
Confidentiality ............................................................................................................... 3 How to use this document ............................................................................................. 4 Revision History ............................................................................................................ 5 1. Overview ................................................................................................................ 6 The Process .............................................................................................................. 6 Workflow Schematics ............................................................................................ 6 Data and Fund Exchanges .................................................................................... 7 Communication Security ........................................................................................... 7 Sandbox/Testing Environment .................................................................................. 8 Payee Management .................................................................................................. 8 2. Payee Sign-up ....................................................................................................... 9 3. Payee Sign-up / Auto Population ......................................................................... 11 XML Parameters .................................................................................................. 12 4. Instant Process Completion Notification .............................................................. 15 5. Payoneer API....................................................................................................... 17 Function: Echo ........................................................................................................ 17 Function: GetVersion ............................................................................................... 18 Function: Payment Order Submission ..................................................................... 19 Function: Query Account Balance Method .............................................................. 21 Function: Get Payee Details .................................................................................... 22 Function: Change Payee ID .................................................................................... 24 Function: Get Payees Report .................................................................................. 26 Function: Get Single Payee Report ......................................................................... 28 Function: Send Message To Payee ........................................................................ 29 Function: Send Message To All Payees .................................................................. 30 Function: Get Unclaimed Payments XML ................................................................ 31 Function: Get Unclaimed Payments CSV ................................................................ 33 Function: Cancel Payment ...................................................................................... 34 6. InterPay via Web Based Admin Console ............................................................. 35 Payee List ............................................................................................................... 35 Mass Payment......................................................................................................... 36 Perform Single Payment ......................................................................................... 37 7. Payee Virtual Card Sign-up ................................................................................. 38 XML Parameters .................................................................................................. 40 Function: Get Card Token ................................................................................... 44 Payoneer Virtual Card - ....................................................................................... 45 Appendices ................................................................................................................. 47 Appendix B Payoneer Mass Payment XML File Format ....................................... 48 Appendix C Payoneer Mass Payment CSV File Format ...................................... 50 Appendix D Field Validations................................................................................ 51 Appendix E Partner Account Setup Process ........................................................ 52
Page 2
Confidentiality
By proceeding, you hereby acknowledge that all the information contained herein constitutes valuable property and trade secrets of Payoneer Inc, which are strictly confidential. You agree that you shall not directly or indirectly: 1. Use or permit the use of this document for, or in connection with, any other business whatsoever, or for any purpose other then the analysis of the project contemplated hereby, or 2. 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 Inc of the circumstances surrounding any breach of this confidentiality of which you become aware.
Page 3
Page 4
Revision History
Date
June 23, 2010
Change Description
June 23, 2010 June 23, 2010 June 23, 2010 June 23, 2010 June 23, 2010
Added new Payee Is Inactive status for payees in PaymentOrderSubmission API 010 - Payee Is Inactive status is for payees who have registered with Payoneer but are not yet approved (Please note: Payee does not exist status is for payees who have not yet registered with Payoneer. These payee status details are provided during the PaymentOrderSubmission API. GetPayeeDetails API card status change to include only active/inactive payee status - other status types are not supported GetPayeeDetails API change to include only the active card of the payee other Card statuses are not supported GetPayeesReport limitation for 1 month period. Remove Escrow payments. Remove Get Unfinished Visits Reports API Remove CashCard Program
Page 5
1. Overview
Payoneer Inc provides a full-scale, easy-to-implement solution for fund disbursement. Operating the solution includes two steps: 1. Payee registration, performed on branded web pages fully hosted by Payoneer; 2. Payment instruction submission to Payoneer, via one of the two supported interfaces: a. Automated interface HTTPS Request/Response interfaces are available to automate data submission and to retrieve reports. The APIs are described further in this document; the specific credentials for submitting API calls are provided at the time of partner account setup. b. Manual interface Payoneer Web Admin Console (InterPay) provides a convenient interface for manual data submission and access to reports. InterPay supports initiation of a single payment as well as large batch file uploads.
The Process
Workflow Schematics
Page 6
Communication Security
To ensure communication safety and message integrity, Payoneer's platform has been enhanced with a wide range of standard and proprietary security measures. Some of the measures are listed below: 1. Validation of the originating IP address: Originating IP addresses of all partner communications are validated against a list of confirmed IPs pre-defined for each partner account (used for all applications). 2. API Permission system: Partners may only use the API functions they need in accordance with their contract with Payoneer Inc. No unauthorized API calls are allowed and all calls are logged. 3. SSL-protected communications: Electronic communications are performed via an SSL-protected channel. 4. Password protected communications: API calls are authenticated using username and password allocated for partners at the time of account setup.
Page 7
Sandbox/Testing Environment
Use the Sandbox Test Environment to manage test accounts and their associated emails and API credentials and functions. The Payoneer Sandbox is a self-contained environment in which you can prototype and test your integration with Payoneer systems and applications. Before moving any Payoneer-based application/web site into production, you should test the application in the Sandbox to ensure that it functions as you intend and within the guidelines and standards set forth by Payoneer. The Sandbox is for use by developers of business solutions. Sandbox credentials will be sent by Payoneers Professional services department in an email. URLs: To access the Sandbox environment you will need to use a separate set of URLs, the credentials for both Sandbox and Productions environment will be the same. This means that the move from Sandbox to Production will involve changing only the base URLs. API URL: https://api.sandbox.payoneer.com/payouts/HttpApi/Api.aspx?parameters Partner Admin Console URL: http://partners.sandbox.payoneer.com/WebApps/Admin/Login.aspx
Payee Management
Prior to issuing payment instructions, the partner account balance at Payoneer needs to be credited accordingly. The account funding procedure is agreed upon contractually between Payoneer and the partner. Payout instruction submission will fail if the partner account balance does not have sufficient funds to perform the card loads. Payoneer API and InterPay are the two interfaces available for submitting payment instructions to Payoneer.
Page 8
2. Payee Sign-up
The payee sign-up page URL is unique and is generated by Payoneer specifically for each sign-up session. The URL is provided in response to a request submitted via HTTP of the following form: https://APIURL/API.aspx?mname=GetToken&p1=username&p2=password &p3=X&p4=Y&p5=A&p6=U&p7=MC&p8=T&p9=y Note: This URL is not the URL to be used for payee redirection!
Description
[Required] This is the method name. [Required] partner account username assigned by Payoneer Inc (provided upon setup of the partner account profile) [Required] unique partner password assigned by Payoneer Inc (provided upon setup of the partner account profile) [Required] Unique partner ID assigned by Payoneer. [Required] Unique payee ID as used within the partner system. [Optional] Payee session ID on the partner Web site. If provided, Payoneer sends it back upon process completion. [Optional] URL used by Payoneer for redirecting the payee back after completion of the sign-up process. [Optional] Token representing the type of the card that the cardholder is allowed to order. Options: ATM or MC (default). [Optional] The delay in seconds between
Data Type
AlphaNumeric AlphaNumeric
AlphaNumeric
p3 (HTTP API) Partner Id p4 (HTTP API) Partner Payee Id p5 (HTTP API) Session Id p6 (HTTP API) Redirect URL p7 (HTTP API) Card Type p8 (HTTP API)
AlphaNumeric
String ATM or MC
Numeric
Page 9
*See Field Validations on Appendix D Payoneer's server response contains the unique URL to the payee sign-up page. The payee then needs to be redirected to this URL for completion of the registration process. Example of a sign-up page URL (No XML):
https://payouts.payoneer.com/partners/lp.aspx?token=
Or (XML):
<?xml version="1.0" encoding="UTF-8" ?> - <PayoneerToken> <Token>https://payouts.payoneer.com/partners/lp.aspx?token= </Token> </PayoneerToken>
Page 10
Description
[Required] This is the method name. [Required] partner account username assigned by Payoneer Inc (provided upon setup of the partner account profile) [Required] unique partner password assigned by Payoneer Inc (provided upon setup of the partner account profile) [Required] Unique partner ID assigned by Payoneer. [Required] Unique partner ID assigned by Payoneer.
Data Type
AlphaNumeric AlphaNumeric
AlphaNumeric
*See Field Validations on Appendix D Sample of XML String: <?xml version="1.0" encoding="UTF-8" ?> <PayoneerDetails> <Credentials> <userName>useruser</userName> <password>xxxxxx</password> </Credentials> <Details> <prid>partnerId</prid> <apuid>payeeId</apuid> <sessionid></sessionid> <redirect></redirect>
Page 11
Payoneer Prepaid MasterCard is the perfect choice for you! <redirectTime>20</redirectTime> <cardType>MC</cardType> <BlockType>0</BlockType> </Details> <PersonalDetails> <firstName>John</firstName> <lastName>Doe</lastName> <dateOfBirth>08091974</dateOfBirth> <address1>642W 42nd St.</address1> <address2>Ste 5E</address2> <city>New York</city> <country>US</country> <state>NY</state> <zipCode>10022</zipCode> <mobile></mobile> <phone>2125551234</phone> <email>me@payoneer.com</email> </PersonalDetails> </PayoneerDetails>
XML Parameters
Parameter
userName Partner Username password Partner Password prid Partner Id apuid Partner Payee Id sessionid Session Id redirect Redirect URL
Description
[Required] partner account username assigned by Payoneer Inc (provided upon setup) [Required] unique partner password assigned by Payoneer Inc (provided upon setup) [Required] Unique partner ID assigned by Payoneer. [Required] Unique payee ID as used within the partner system. [Optional] Payee session ID on the partner Web site. If provided, Payoneer sends it back upon process completion. [Optional] URL used by Payoneer for redirecting the payee back after completion of the sign-up process
Data Type
AlphaNumeric
AlphaNumeric
AlphaNumeric 0
Page 12
Numeric 0-6
Numeric
firstName Partner Payee first name lastName Partner Payee last name dateOfBirth Partner Payee birth date address1 Partner Payee address address2 Partner Payee secondary address city Partner Payee city country Partner Payee country state Partner Payee state
AlphaNumeric 30 Chars AlphaNumeric 30 Chars AlphaNumeric AlphaNumeric ISO2 code AlphaNumeric State code
Page 13
Response
A XML formatted string, containing the unique URL to the payee sign-up page and information about the new cardholder created. The URL is valid for a single payee registration. Example:
<?xml version="1.0" encoding="UTF-8" ?> <PayoneerToken> <Token>http://payouts.payoneer.com/partners/lp.aspx?token=XXXAAAB</Token> <CardholderSignup> <Description><!-- If Status is not 000, This will 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 Inc system --> </PayoneerID> </CardholderSignup> </PayoneerToken>
Page 14
Page 15
Payoneer Prepaid MasterCard is the perfect choice for you! Load Money to ACH IPCN: after funds are sent to ACH payee. Example: https://www.partnercompany.com/payoneer_confirmation.aspx?LOADA CH=true&payeeid={{apuid}}
Payment Request Accepted IPCN: after Payoneer send the funds to the Payee. Example: https://www.partnercompany.com/payoneer_confirmation.aspx?PAYME NT=true&payeeid={{apuid}} Note: once Payoneer approves payee card application (see IPCN Approved above) payee ID exists in the Payoneer system and Partner can submit payments to the Payee.
Page 16
5. Payoneer API
Function: Echo
Http usage: https://APIURL/API.aspx?mname=Echo This method returns the status of the API and Payout Services (Heart Beep). Request Parameters
Field
mname (HTTP API) p1 (HTTP API) Partner Username
Description
[Required] This is the method name. [Required] partner account username assigned by Payoneer Inc (provided upon setup of the partner account profile) [Required] unique partner password assigned by Payoneer Inc (provided upon setup of the partner account profile) [Required] partner account ID number at Payoneer Inc (provided upon setup of the partner account profile)
Data Type
AlphaNumeric AlphaNumeric
AlphaNumeric
AlphaNumeric
Response
A string that is an XML file formatted as following:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <PayoneerResponse> <Status> </Status> <Description> </Description> </PayoneerResponse>
Code table:
000 001 002 OK System down for scheduled maintenance System down
Page 17
Function: GetVersion
Http usage: https://APIURL/API.aspx?mname=GetVersion This method returns the API version (to match with the relevant integration guide). Request Parameters
Field
mname (HTTP API) p1 (HTTP API) Partner Username
Description
[Required] This is the method name. [Required] partner account username assigned by Payoneer Inc (provided upon setup of the partner account profile) [Required] unique partner password assigned by Payoneer Inc (provided upon setup of the partner account profile) [Required] partner account ID number at Payoneer Inc (provided upon setup of the partner account profile)
Data Type
AlphaNumeric AlphaNumeric
AlphaNumeric
AlphaNumeric
Response
A string that is an XML file formatted as following:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <PayoneerResponse> <Version> </Version> </PayoneerResponse>
Page 18
Request Parameters
Field
mname (HTTP API) p1 (HTTP API) Partner username p2 (HTTP API) Partner password p3 (HTTP API) Partner ID p4 (HTTP API) Program ID p5 (HTTP API) Internal Payment ID p6 (HTTP API) Internal Payee ID p7 (HTTP API) Amount
Description
[Required] The method name. [Required] Partner account username assigned by Payoneer Inc [Required] Partner password assigned by Payoneer Inc [Required] Partner ID at Payoneer Inc as supplied during the partner account setup [Required] Program code at Payoneer Inc as supplied when the partner account setup [Required] Unique payment ID assigned by the partner [Required] Payee ID as set in the Partner system. [Required] Payment amount in USD. Fees charged to payees are deducted from this amount. Payments lower than the minimum payment amount will be rejected. [Required] Payment description [Required] Date of payment, usually today's date
Data Type
AlphaNumeric AlphaNumeric AlphaNumberic AlphaNumeric AlphaNumeric AlphaNumeric No special chars AlphaNumeric No special chars Decimal
Page 19
Response
A string that is an XML file formatted as following:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <PerformPayoutPayment> <Description><!-- If Status is not 000, This will 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 Inc system --> </PayoneerID> </PerformPayoutPayment>
Page 20
Request Parameters
Field
mname (HTTP API) p1 (HTTP API) Partner Username p2 (HTTP API) Partner Password p3 (HTTP API) Partner ID
Description
[Required] This is the method name. [Required] This will be the partner account username assigned by Payoneer Inc. [Required] This will be the unique partner password assigned by Payoneer Inc. [Required] This will be the partner account ID number at Payoneer Inc. It will be supplied when setup the partner account profile.
Data Type
AlphaNumeric AlphaNumeric Tokenized AlphaNumberic AlphaNumeric
Response
A string that is an XML file formatted as following:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <GetAccountDetails> <FeesDue><!-- Fees due by partner to Payoneer Inc --> </FeesDue> <AccountBalance> <!-- Balance remaining in the Partners Account for payments --> </AccountBalance> </GetAccountDetails>
Page 21
Description
[Required] This is the method name. [Required] partner account username assigned by Payoneer Inc (provided upon setup of the partner account profile) [Required] unique partner password assigned by Payoneer Inc (provided upon setup of the partner account profile) [Required] partner account ID number at Payoneer Inc (provided upon setup of the partner account profile) [Required] Partner Payee ID as appears in the Payoneer Inc system
Data Type
AlphaNumeric AlphaNumeric
AlphaNumeric
AlphaNumeric
Response
A string that is an XML file formatted as following:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <GetPayeeDetails> <Payee> <FirstName></FirstName> <LastName></LastName> <Address1></Address1> <Address2></Address2> <City></City> <State></State> <Zip></Zip> <Country></Country> <Email></Email> <Phone></Phone> <Mobile></Mobile> <PayOutMethod></PayOutMethod><!--Prepaid Card/Direct deposit/Paypal --> <Cards><!-- if it is Prepaid Card --> <Card><!--for active card-->
Page 22
Card Statuses:
Inactive Active Card cannot be used (no funds available on the card or card is blocked) Card can be used at ATMs, POS and Online
Page 23
Request Parameters
Field
mname (HTTP API) p1 (HTTP API) Partner Username
Description
[Required] This is the method name. [Required] partner account username assigned by Payoneer Inc (provided upon setup of the partner account profile) [Required] unique partner password assigned by Payoneer Inc (provided upon setup of the partner account profile) [Required] partner account ID number at Payoneer Inc (provided upon setup of the partner account profile) [Required] Partner Payee ID as appears in the Payoneer Inc system [Required] New Partner Payee ID to set
Data Type
AlphaNumeric AlphaNumeric
AlphaNumeric
AlphaNumeric
Response
A string that is an XML file formatted as following:
<?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>
Page 24
Payoneer Prepaid MasterCard is the perfect choice for you! Code table:
000 001 002 003 OK Payee does not exist in the Payoneer system Internal error New Payee ID already exists
Page 25
Description
[Required] This is the method name. [Required] partner account username assigned by Payoneer Inc (provided upon setup of the partner account profile) [Required] unique partner password assigned by Payoneer Inc (provided upon setup of the partner account profile) [Required] partner account ID number at Payoneer Inc (provided upon setup of the partner account profile) [Required] type of report to generate. At this time only XML report is supported [Optional] Date of payment to start looking from [Optional] Date of payment to end search with
Data Type
AlphaNumeric AlphaNumeric
AlphaNumeric
AlphaNumeric
p4 (HTTP API) Report Type P5 (HTTP API) Start Date P6 (HTTP API) End Date
Response
A string that is an XML file formatted as following:
<?xml version="1.0" encoding="utf-8" standalone="no"?> <PayoneerPayees> <Prepaid> <!here are listed all the payees that have registered for Prepaid:--> <Payee> <PayeeId></PayeeId> <Name> </Name> <Email> </Email> <RegistrationDate> </RegistrationDate> <Status> </Status> <TotalAmount></TotalAmount>
Page 26
Page 27
Request Parameters
Field
mname (HTTP API) p1 (HTTP API) Partner Username
Description
[Required] This is the method name. [Required] partner account username assigned by Payoneer Inc (provided upon setup of the partner account profile) [Required] unique partner password assigned by Payoneer Inc (provided upon setup of the partner account profile) [Required] partner account ID number at Payoneer Inc (provided upon setup of the partner account profile) [Required] Partner Payee ID as appears in the Payoneer Inc system
Data Type
AlphaNumeric AlphaNumeric
AlphaNumeric
AlphaNumeric
Response
A string that is an XML file formatted as following:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <PayoneerPayees> <Prepaid> <Payee> <Name> </Name> <Email> </Email> <RegistrationDate> </RegistrationDate> <Status> </Status> <TotalAmount> </TotalAmount> <Payments> <Payment> <Date> </Date> <PaymentID> </PaymentID> <Amount> </Amount> <Status> </Status> <Description> </Description> </Payment> </Payments> </Payee> </Prepaid></PayoneerPayees>
Page 28
Description
[Required] This is the method name. [Required] partner account username assigned by Payoneer Inc (provided upon setup of the partner account profile) [Required] unique partner password assigned by Payoneer Inc (provided upon setup of the partner account profile) [Required] partner account ID number at Payoneer Inc (provided upon setup of the partner account profile) [Required] Partner Payee ID as appears in the Payoneer Inc system [Required] The subject of the message [Required] The body of the message [Required] The name of the sender of the message
Data Type
AlphaNumeric AlphaNumeric
AlphaNumeric
AlphaNumeric
p4 (HTTP API) Payee ID P5 (HTTP API) Subject P6 (HTTP API) Message P7 (HTTP API) From
Response
A string that is an XML file formatted as following:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <SendMessageToPayee> <PayeeID></PayeeID> <Subject> </Subject> <Result></Result> <!000 if send, 001 if failed --> <Description> </Description> </SendMessageToPayee>
Page 29
Description
[Required] This is the method name. [Required] partner account username assigned by Payoneer Inc (provided upon setup of the partner account profile) [Required] unique partner password assigned by Payoneer Inc (provided upon setup of the partner account profile) [Required] partner account ID number at Payoneer Inc (provided upon setup of the partner account profile) [Required] The subject of the message [Required] The body of the message [Required] The name of the sender of the message
Data Type
AlphaNumeric AlphaNumeric
AlphaNumeric
AlphaNumeric
Response
A string that is an XML file formatted as following:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <SendMessageToAllPayees> <Subject> </Subject> <Result></Result> <!000 if send, 001 if failed --> <Description> </Description> </SendMessageToAllPayees>
Page 30
AlphaNumeric
AlphaNumeric
Response
A string that is an XML file formatted as following:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <GetUnclaimedPayments> <Payment> <IntPayeeId> </IntPayeeId><!--as assigned by partner --> <IntPaymentId> </IntPaymentId><!--as assigned by partner -> <PayoneerPaymentId> </PayoneerPaymentId><!--internal payoneer reference --> <Amount></Amount><!-- as calculated in payment --> <!--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>
Page 31
Page 32
Description
[Required] This is the method name. [Required] partner account username assigned by Payoneer Inc (provided upon setup of the partner account profile) [Required] unique partner password assigned by Payoneer Inc (provided upon setup of the partner account profile) [Required] partner account ID number at Payoneer Inc (provided upon setup of the partner account profile)
Data Type
AlphaNumeric AlphaNumeric
AlphaNumeric
AlphaNumeric
Response
A comma separated string where each row contains the following information:
IntPayeeId*,IntPaymentId*,PaymentId,Amount,FirstName,LastName,Address1, Address2,City,State,Zip,Country,Email,Phone,Mobile,PayOutMethod,PaymentDate, Description
* IntPayeeId is the payee Id as set in the partner's system * IntPaymentId is the payment Id as set in the partner's system
Page 33
Description
[Required] This is the method name. [Required] partner account username assigned by Payoneer Inc (provided upon setup of the partner account profile) [Required] unique partner password assigned by Payoneer Inc (provided upon setup of the partner account profile) [Required] partner account ID number at Payoneer Inc (provided upon setup of the partner account profile) [Required] Partner Payment ID as assigned upon payment
Data Type
AlphaNumeric AlphaNumeric
AlphaNumeric
AlphaNumeric
AlphaNumeric
Response
A string that is an XML file formatted as following:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <CancelPayment> <PaymentID> </PaymentID><!-- of the cancelled payment --> <Result> </Result><!000 means success, otherwise see table --> <Amount> </Amount><!-- of the cancelled payment --> <Description> </Description><!-- of the cancelled payment --> </CancelPayment>
Code table:
000 001 002 003 004 005 OK Payment does not exist payment has already been processed payment has already been cancelled / rejected Failed to cancel payment Payment cancelled, but failed to return money to partner's balance
Page 34
1. Payee List
When entering the InterPay tab on the Admin Console, the payee list will appear. To send payment instructions you will be required to enter the amount, description and payment id. Once completed, click on Update and then Pay. Confirmation page window will appear with the requested payments. Verify the payment then click on the Process Payment button and payments will be transmitted to Payoneer and to your Payees.
Page 35
2. Mass Payment
InterPay supports mass payment option by creating an XML or CSV file in the Payoneers format (see Appendix B and C for file format) and uploading it to Payoneer using the web interface.
After the file is uploaded, the payments from the file will be presented on the screen for your review. Verify the payments and click on the Process Payment button. The payments will be transmitted to Payoneer and to your Payees.
Page 36
Page 37
Description
[Required] This is the method name. [Required] partner account username assigned by Payoneer Inc (provided upon setup of the partner account profile) [Required] unique partner password assigned by Payoneer Inc (provided upon setup of the partner account profile) [Required] Unique partner ID assigned by Payoneer. [Required] Unique partner ID assigned by Payoneer.
Data Type
AlphaNumeric AlphaNumeric
AlphaNumeric
Page 38
Sample of XML String: <?xml version="1.0" encoding="UTF-8" ?> <PayoneerDetails> <Credentials> <userName>useruser</userName> <password>xxxxxx</password> </Credentials> <Details> <prid>partnerId</prid> <apuid>payeeId</apuid> <cardType>VC</cardType> </Details> <PersonalDetails> <firstName>John</firstName> <lastName>Doe</lastName> <dateOfBirth>08091974</dateOfBirth> <address1>642W 42nd St.</address1> <address2>Ste 5E</address2> <city>New York</city> <country>US</country> <state>NY</state> <zipCode>10022</zipCode> <mobile></mobile> <phone>2125551234</phone> <email>me@payoneer.com</email> <IdType>4</IdType> <IdNumber>66655544</IdNumber> <NameOnId>Amir Tatarsky</NameOnId> <IdCountry>Israel</IdCountry> <IdExpDate>08092020</IdExpDate> <PassportIssueDate>08092021</PassportIssueDate> </PersonalDetails> <VirtualCard> <CredentialName>Promo code</CredentialName> <CredentialValue>232547567</CredentialValue> <AmounttoLoad>20.00</AmounttoLoad> <PaymentDescription>card load</PaymentDescription> </VirtualCard> </PayoneerDetails>
Page 39
XML Parameters
Parameter
userName Partner Username password Partner Password prid Partner Id apuid Partner Payee Id cardType Card Type
Description
[Required] partner account username assigned by Payoneer Inc (provided upon setup) [Required] unique partner password assigned by Payoneer Inc (provided upon setup) [Required] Unique partner ID assigned by Payoneer. [Required] Unique payee ID as used within the partner system. [Required] Token representing the type of the card that the cardholder is allowed to VC Virtual Card Will only be allowed for partners with special permissions. [Required] will be used for cardholder registration [Required] will be used for cardholder registration [Optional] must be in MMDDYYYY format [Required] will be used for cardholder registration [Optional] will be used for cardholder registration [Required] will be used for cardholder registration [Required] will be used for cardholder
Data Type
AlphaNumeric
AlphaNumeric
firstName Partner Payee first name lastName Partner Payee last name dateOfBirth Partner Payee birth date address1 Partner Payee address address2 Partner Payee secondary address City Partner Payee city country Partner Payee
Page 40
IdNumber ID Number NameOnid Name on ID IdCountry Country Issued ID IdExpDate ID Expiration Date
Numeric
Numeric
Page 41
AlphaNumeric
MaxLength=50
AlphaNumeric
MaxLength=50 Decimal
Payment Description
Response
An XML formatted string, containing the unique URL to the payee sign-up page and information about the new cardholder created. The URL is valid for a single payee registration. Example:
<?xml version="1.0" encoding="UTF-8" ?> <PayoneerToken> <Token>http://payouts.payoneer.com/partners/lp.aspx?token=XXXAAAB</Token> <CardholderSignup> <Description><!-- If Status is not 000, This will 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 Inc system --> </PayoneerID> </CardholderSignup> </PayoneerToken>
Page 42
Payoneer Prepaid MasterCard is the perfect choice for you! Status code table:
000 001 003 004 005 006 007 008 009 099 044 045 PE1001 PE1004 PE1005 PE1006 PE1010 FFA009A 000FFF0 A00B556F OK (Request accepted) Field format is invalid or is not supported Insufficient funds Payment Id already exists Internal error Internal error Cannot load negative amount Exceeded minimum loading limit Exceeded maximum loading limit Unauthorized access Payee ID already exists Email already exists No XML Received UserName/Password not match to partner ID No partner id received No payee id received Unauthorized action Auto populate XML contains invalid entries API Function Not Allowed By Partner Unauthorized Access or invalid parameters, please check your IP address and parameters
Page 43
Request Parameters
Field
Description
[Required] This is the method name.
DataType
AlphaNumeric
[Required] partner account username assigned by Payoneer Inc (provided upon setup of the partner account profile) [Required] unique partner password assigned by Payoneer Inc (provided upon setup of the partner account profile)
AlphaNumeric
AlphaNumeric
[Required] Unique payee ID as used within the partner system. (Order ID)
Response
Payoneer's server response contains the unique URL to the registration. A string that is an XML file formatted as following:
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?> <PayoneerCardToken> <URL><!A tokened link to the registration and activation page --> </URL> </PayoneerCardToken>
Page 44
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
Payee ID First Name Last Name e-mail Address 1 Address 2 city State Zip Code country Phone Number Mobile Number Date Of Birth Credential Name Credential Value Amount To Load Payment Description ID Type
The id this payee has in your system. Partner Payee first name Partner Payee last name Partner Payee e-mail address Partner Payee address [optional] Partner Payee secondary address Partner Payee city [optional] Partner Payee state - State code (iso_3166) Partner Payee zip Partner Payee country ISO2 code (iso_3166) [optional] Partner Payee Phone Number [optional] Partner Payee Mobile Number [optional] Partner Payee Date Of Birth must be in MMDDYYYY format The credential name that will appear as prompt in login to the card information. The value of the credential will be expected in login to the card information. Payment amount in USD. Payment description 1=SSN 2=Driver License 3=National ID 4=Passport Number
19 20
IF ID Type = 1 [SSN] Name on Card Social Security Number Partner Payee Name imprinted on the card Partner Payee Social Security Number
19 20 21
IF ID Type = 2 [Driver License] Driver License Name Driver License Id Driver License Partner License Partner Partner Payee Driver License Name imprinted on the Driver card Payee Driver License Id Payee Driver License Issue Country ISO2 code
Page 45
22
IF ID Type = 3 [National ID] National ID Name National ID number National ID Issue Country Partner Payee Name imprinted on the National ID card Partner Payee National ID number Partner Payee National ID Issue Country ISO2 code (iso_3166)
19 20 21 22 23
IF ID Type = 4 [Passport] Passport Name Passport Passport Country Passport Date Passport Date ID Issue Issue Expired Partner Payee Name imprinted on the Passport Partner Payee Passport ID Partner Payee passport issued country ISO2 code (iso_3166) Partner Payee Passport Issue Date must be in MMDDYYYY format Partner Payee Passport Expired Date must be in MMDDYYYY format
Mass Registration Tips: To generate a Mass Payment file from Excel, save the file as CSV Comma Delimited If you are using another software application, make sure the program you are using allows you to save in Comma-delimited format. Up to 3,000 records per single upload file. Each line should include unique payee id/email that cannot ever be repeated. If Country is U.S, State field is required. Each line should be separated by a carriage return. (In Excel, this is done automatically.) Please notice that the order of the fields is important. For Field Validation please refer to PayoneerPayoutsIntegrationGuide Appendix D
Page 46
Appendices
Appendix A - Payment Failure Codes:
001 002 003 004 005 009 010 099 Field format incorrect or not supported Payee does not exist insufficient funds payment already exists Internal error Internal error Payee is Inactive Unauthorized access
Page 47
2 3 4 5 6 7
Page 48
Page 49
Group ID
Page 50
SSN DriverLicense Number NationalID number PassportID NameOnCard Credential Name CredentialValue
Validcharacters Alfanumeric,whitespaces,.,/,_,,),(,\,&,@,#,`,comma,* Alphanumeric,whitespaces,.,/,_,,),(,\,&,@,#,`,comma,* Digits,comma,., Letters,space, TwoLetters Canbeparsedtoadateusing.netinfrastructure Alfanumeric,whitespaces,(,),/,.,,@,%,!,_,:,$,",+,> Letters,space,digits Lettersanddigits,_,,^,(,),@,/,!,#,space,$,.,: Letters,space,digits Lettersanddigits,_,,^,@,!,?,",. Lettersanddigits,!,@,#,$,%,^,& (,),digits, Digits Digits,letters,.,!,,(space) TwoLetters Letters,digits,space, 1,2,3,4 Digits Letters,digits Letters,digits Letters,digits Letters,digits,space,,_,. Letters,?,',space Letters,digits,space
Min Len. 7 6 1 3 1 4
Page 51
Page 52