Docs
DocumentationAPI ReferenceAsk AI Assistant
  • Home
    • Get Your Business Started
    • Services and Supported Features
  • Documentation
    • Developer Quickstart
      • Authentication
      • Card Sales and Consent
      • Querying and Filtering
      • Payment Reminders
    • Getting Started
      • Integration Checklist
      • Integration Options
        • REST API
        • Android SDK
        • iOS SDK
        • React Native Wrapper
        • PayForm
        • Verifone
        • Virtual Terminal
      • Basics
        • Authentication
        • API Best Practices
        • API Input Validation
        • Testing Considerations
      • Client Admin Portal
    • Testing
      • Testing Overview
      • Global Payments Testing
      • First Data Testing
      • ACH Testing
    • Resources
      • Tools and Downloads
      • Vocabulary
      • Querying
      • Error Codes
      • Software Requirements
  • API Reference
    • REST API
      • Authentication
      • ACH
      • Card Operations
        • Process a Card Sale
      • Consent Annual
        • Create Annual Consent
      • Consent Recurring
        • Create Recurring Consent
      • Consent Subscription
      • International
      • PayForm
      • Query
        • Account
        • ACH
        • Batch
        • Consent Annual
        • Consent Recurring
        • Consent General
        • Recurring Schedule
        • Receipt
        • Transaction
        • Voice
        • Query General
        • Reconcile
      • Receipt
      • Recurring Schedule
      • Settlement
      • Text to Pay
  • Help
    • Customer Support
      • FAQ
Powered by GitBook

Copyright © Number

On this page

Was this helpful?

Export as PDF
  1. API Reference
  2. REST API

International

PreviousConsent SubscriptionNextPayForm

Last updated 4 months ago

Was this helpful?

  • POSTGenerate a receipt for an international transaction
  • POSTProcess a payment consent for international transactions
  • POSTQuery international transactions
  • POSTVoid an international transaction

Generate a receipt for an international transaction

post

REFID will be the transaction ID
ReceiptType will always be 23 for International
Merchant copy use Recipient = 1
Customer Copy use Recipient = 2
For Dual Receipt use Recipient = 3

Consuming the Response
The member named ReceiptHtml holds the receipt data
Important you must replace all Unicode characters to consume clean HTML
Example : CleanHtml = Regex.Replace(my, @"[^\u0000-\u007F]+", string.Empty);

Header parameters
SessKeystringRequired

A unique session key used for authentication in API calls. This key is generated upon successful authentication and must be included in all subsequent requests.

Example: A1842D663E9A4A72XXXXXXXX303541303234373138
Content-TypestringRequiredExample: application/json
AcceptstringRequiredExample: application/json
Body
REFIDstringOptional

The transaction ID

Example: 5eef4782-5be1-11ef-bbc1-46647bd59a7a
ReceiptTypeintegerOptional

The type of receipt, 23 for international

Example: 23
Recipientinteger · enumOptional

The targeted recipient type

  • 1: Merchant
  • 2: Customer
  • 3: Both
Example: 1Possible values:
Responses
200
Successfully generated receipt
application/json
post
POST /APIcardProcREST/v1.0.0/Intl/ReceiptGenerate HTTP/1.1
Host: easypay5.com
SessKey: A1842D663E9A4A72XXXXXXXX303541303234373138
Content-Type: application/json
Accept: application/json
Content-Length: 79

{
  "REFID": "5eef4782-5be1-11ef-bbc1-46647bd59a7a",
  "ReceiptType": 23,
  "Recipient": 1
}
200

Successfully generated receipt

{
  "Intl_ReceiptGenerateResult": {
    "ErrCode": 0,
    "ErrMsg": "",
    "FunctionOk": true,
    "ReceiptHtml": "<!DOCTYPE html><html xmlns=\"http://www.w3.org/1999/xhtml\"><head runat=\"server\"><meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />    <title></title></head><body>    <form id=\"form1\" runat=\"server\"><div style=\" font-size:12px;font-family:Verdana\" align=\"center\"><h3>SALE RECEIPT</h3><br /><div><label>TEST MERCHANT TWO</label><br /><label>222 RAND ROAD</label><br /><label>LONDON, AK 54321</label><br /><label>(555) 555-5555</label></div><br />  <br /><table style=\"text-align:left\"><tr><td>CARDHOLDER NAME:</td><td><label>Smith, Nancy</label></td></tr><tr><td>ACCT NUMBER:</td><td><label>x1111</label></td></tr><tr><td>EXP DATE:</td><td><label>xxxx</label></td></tr><tr><td>TX ID:</td><td><label>5eef4782-5be1-11ef-bbc1-46647bd59a7a</label></td></tr><tr><td><label>PATIENT</label> REF ID:</td><td><label>N/A</label></td></tr><tr><td>TX DATE:</td><td><label>8/16/2024 11:08:23 AM</label></td></tr><tr><td>CARD TYPE:</td><td><label>VI</label></td></tr><tr><td>ENTRY METHOD:</td><td><label>Manual Entry</label></td></tr><tr><td>AMOUNT:</td><td><asp:label runat=\"server\">£8.14 GBR</asp:label></td></tr><tr><td></td><td><asp:label runat=\"server\"></asp:label></td></tr><tr><td>TOTAL(GBP):</td><td><label>£8.14 GBR</label></td></tr></table><br /><div><label>THANK YOU FOR YOUR PATRONAGE</label><br /><label>All Sales Final</label><br /><div><label>I agree to pay TEST MERCHANT TWO the above amount according to card issuer agreement.</label></div><br /><br /><div><label>SIGNATURE</label></div><br /><div>___________________________________</div><h3><b>MERCHANT COPY</b></h3></div></div></form></body></html>",
    "RespMsg": "Successfully Returned Transaction Receipt Markup"
  }
}

Process a payment consent for international transactions

post

This API call is for merchant accounts that are specifically configured for international processing.

Header parameters
SessKeystringRequired

A unique session key used for authentication in API calls. This key is generated upon successful authentication and must be included in all subsequent requests.

Example: A1842D663E9A4A72XXXXXXXX303541303234373138
Content-TypestringRequiredExample: application/json
AcceptstringRequiredExample: application/json
Body
TokenIDstringOptional

The consent token ID for the transaction returned when creating a sale using the international widget

Example: a64d8a2a-5994-11ef-95fc-3e580ecac30f
ChargeAmtnumber · floatOptional

The amount to be charged

Example: 5
Responses
200
Successfully processed the payment consent
application/json
post
POST /APIcardProcREST/v1.0.0/Intl/ProcPayment HTTP/1.1
Host: easypay5.com
SessKey: A1842D663E9A4A72XXXXXXXX303541303234373138
Content-Type: application/json
Accept: application/json
Content-Length: 64

{
  "TokenID": "a64d8a2a-5994-11ef-95fc-3e580ecac30f",
  "ChargeAmt": 5
}
200

Successfully processed the payment consent

{
  "Intl_ProcPaymentResult": {
    "AuthorizedAmt": 5,
    "ErrCode": 0,
    "ErrMsg": "",
    "FunctionOk": true,
    "RespMsg": "Successfully charged Consent a64d8a2a-5994-11ef-95fc-3e580ecac30f For $5.00",
    "TransID": "a63f6936-5994-11ef-8613-3e580ecac30f",
    "TxApproved": true,
    "TxnCode": ""
  }
}

Query international transactions

post

Query Strings:
EasyPay provides a robust query language which provides a means for you to obtain specific records.

In order to Create a Query you will build logical terms and join them with Logical AND or Logical OR.

Use && for Logical AND

Use || for Logical OR

For instance, Let's say you want to return all records from merchant record 1 which were created in JUNE.

HERE IS THE QUERY: (A=1)&&(C>='6/1/2024')&&(C<'7/1/2024') (notice that any TEXT or DATES use a single Quote delimiter while numeric items do not)

Each Letter represents a variable and the following chart shows each meaning.

A MerchID
B Status
C CreatedON
D LastName
E Result
F TransID
J FirstName
L Amount
M REFID
Q CardNum Last 4
N RPGUID
W ConsentID

EasyPay stores a copy of the transactional data on its servers. For international transactions data is stored in such a way that we may have multiple records in our system for a single credit card authorization or OrderID. Two Fields of Interest are Result and Status.

Seq OrderID Action Result Status
1 09B370DD SALE REDIRECT REDIRECT
2 09B370DD SALE REDIRECT 3DS
3 09B370DD SALE SUCCESS SETTLED

The above table shows three records we record as we process a single transaction on the International Processing Servers. As you request transaction information you are most likely only interested in the last entry which shows SUCCESS and SETTLED as the other two are simply intermediate steps.

The following shows query enum values for RESULT and STATUS and ACTION

E Result Values
ALL -1
SUCCESS 1
DECLINED 2
REDIRECT 3
ACCEPTED 4
ERROR 5
UNDEFINED 6
B Status Values
ALL -1
PENDING 1
REDIRECT 2
SETTLED 3
REVERSAL 4
REFUND 5
DECLINED 6
PENDING 7
CHARGEBACK 8
VOID 9
G Action Values
ALL -1
SALES 1
CREDITVOID 2
RECURRING_SALE 3

So, to return all Transactions which are successfully settled please use the following query:

Result ➔ E Use 1 for Success
Status ➔ B Use 3 for Settled

Your query now becomes the following
{
"Query": "(B=3)&&(E=1)"
}


You can further limit your query by specifying a Date Range

{
"Query": "(B=3)&&(E=1)&&(C>’2024-09-01’)"
}


If you want to limit your results to transactions which are REFUNDS then use ACTION CREDITVOID

Or specifically (G=2)
{
"Query": "(B=3)&&(E=1)&&(C>'2024-09-01')&&(G=2)"
}


If you want to limit your results to transactions which are Processed from stored Card use ACTION RECURRING_SALE

Or specifically (G=3)
{
"Query": "(B=3)&&(E=1)&&(C>'2024-09-01')&&(G=3)"
}


If you are looking for a particular transaction based on its unique TransID, you can do the following:
{
"Query": "(F='328217c4-7059-11ef-a730-a6469c956913')&&(B=3)&&(E=1) "
}
This will return the transaction of interest without returning the intermediate steps as noted above.


If you want to query by Last name on a specific Date
{
"Query": "(C>'2024-09-16')&&(C<'2024-09-17')&&(D='SMITH')&&(B=3)&&(E=1)"
}


If you are looking for a specific Amount
{
"Query": "(L=4.44)&&(B=3)&&(E=1)"
}


If you are looking for a specific Amount within a date range
{
"Query": "(L=4.44)&&(C>'2024-09-16')&&(C<'2024-09-17')&&(B=3)&&(E=1)"
}


If you are looking for a particular Card Number ( use last 4 digits ) for settled records
{
"Query": "(Q='1111')&&(B=3)&&(E=1)"
}


If you are looking for a particular Reference ID
{
"Query": "(M='ABC 888')&&(B=3)&&(E=1)"
}


If you are looking for a particular saved card transaction based on the ConsentID
{
"Query": "(W='c30eca54-75c1-11ef-b9e6-7aa481e33aa5')&&(B=3)&&(E=1)"
}

Header parameters
SessKeystringRequired

A unique session key used for authentication in API calls. This key is generated upon successful authentication and must be included in all subsequent requests.

Example: A1842D663E9A4A72XXXXXXXX303541303234373138
Content-TypestringRequiredExample: application/json
AcceptstringRequiredExample: application/json
Body
QuerystringOptional

A query string for obtaining specific transaction records using Number's query language. Build logical terms and join them with '&&' for logical AND or '||' for logical OR. Use single quotes for text and date values. Refer to the variable chart for query composition:

  • A: MERCHANT ID - The merchant record you are interested in, e.g. (A=1).
  • B: TRANSACTION STATUS - The status of the transaction, e.g. (B=1).
    • -1: ALL
    • 1: OPEN
    • 2: SETTLED
    • 3: FAILED
    • 4: RETURNED
    • 5: VOID
  • C: DATE CREATED - The date the transaction was created, e.g. (C>='7/5/2024 12:00:00 AM').
  • D: LAST NAME - Last name of the account holder, e.g. (D LIKE '%MITH') for all names that end with 'MITH'.
  • E: TRANSACTION LOCK - Lock status of the transaction, e.g. (E<>'0') for locked transactions.
  • H: TRANSACTION ID - The unique identifier for the transaction, e.g. (H=58258).
  • J: FIRST NAME - First name of the account holder, e.g. (J LIKE 'ROB%') for all names that start with 'ROB'.
  • K: TRANSACTION TYPE - The type of transaction, e.g. (K=-1).
    • -1: ALL
    • 1: ACHDEBIT
    • 2: ACHCREDIT
  • L: AMOUNT - The $ amount of the transaction, e.g. (L>100.00).
  • M: CLIENT REFERENCE ID - User-defined value on the transaction.
  • N: RPGUID - User-defined value on the transaction.
  • P: CONSENT ID - The Consent ID of card on file the transactions were charged against, e.g. (P=15875).
  • Q: ACCOUNT NUMBER LAST 4 - The last 4 digits of a credit card, e.g. (Q='4123').
  • R: APPROVAL CODE - The approval code for the transaction, e.g. (R='TAS626').
  • S: CUSTOMER LAST NAME - The last name of the customer, e.g. (S='SMITH').
  • T: CUSTOMER FIRST NAME - The first name of the customer, e.g. (T='FOSTER').
  • U: ORIGIN - The origin of the transaction, e.g. (U='API').
    • "API": REST / SOAP API
    • "WID": Widget
    • "VT": Virtual Terminal
Example: (B=3)&&(E=1)&&(C>'2024-09-01')
Responses
200
Successfully queried transactions
application/json
post
POST /APIcardProcREST/v1.0.0/Intl/QueryTransaction HTTP/1.1
Host: easypay5.com
SessKey: A1842D663E9A4A72XXXXXXXX303541303234373138
Content-Type: application/json
Accept: application/json
Content-Length: 68

{
  "Query": "(F='328217c4-7059-11ef-a730-a6469c956913')&&(B=3)&&(E=1)"
}
200

Successfully queried transactions

{
  "Intl_Transaction_QueryResult": {
    "ErrCode": 0,
    "ErrMsg": "",
    "FunctionOk": true,
    "NumRecords": 1,
    "RespMsg": "Successfully Returned Transaction Records : 1",
    "Transactions": [
      {
        "Action": "SALE",
        "Address": "generating sale",
        "Amount": 0,
        "Card": "0042",
        "CardType": "VI",
        "Card_Expiration_Date": "12/2025",
        "Card_Token": "4332225cc2db2f4de92583af2e6f62d942650909a5a5282138eb393158e27a63",
        "City": "Auburn",
        "Country": "US",
        "CreatedOn": "2024-12-01 11:19:01",
        "Currency": null,
        "Decline_Reason": "",
        "Descriptor": "",
        "Email": "ndraper@easypaysolutions.com",
        "Fname": "Nancy",
        "ID": 570,
        "Lname": "Draper",
        "MerchID": 1,
        "Order_ID": "B7A6A9DF",
        "Phone": "",
        "PostalCode": "32658",
        "REFID": "",
        "RPGUID": "adf98580-b4ab-42fc-bb99-01c89964afe9",
        "Recurring_Token": "a4b1f2ec-5434-11ef-ac32-e62c2d2c5cd6",
        "Result": "SUCCESS",
        "Schedule_ID": null,
        "State": "ME",
        "Status": "3DS",
        "Trans_Date": "Sep 11 2024  4:16PM",
        "Trans_ID": "328217c4-7059-11ef-a730-a6469c956913",
        "bank_date": null,
        "chargeback_date": null,
        "reason_code": null
      }
    ]
  }
}

Void an international transaction

post

This API call is for merchant accounts that are specifically configured for international processing.

Header parameters
SessKeystringRequired

A unique session key used for authentication in API calls. This key is generated upon successful authentication and must be included in all subsequent requests.

Example: A1842D663E9A4A72XXXXXXXX303541303234373138
Content-TypestringRequiredExample: application/json
AcceptstringRequiredExample: application/json
Body
TransIDstringOptional

The transaction ID of the transaction to be voided

Example: a88ed0e4-5a3b-11ef-b49b-46647bd59a7a
CreditAmtnumber · floatOptional

The amount of the transaction to be voided

Example: 5
Responses
200
Successfully voided the transaction
application/json
post
POST /APIcardProcREST/v1.0.0/Intl/VoidCredit HTTP/1.1
Host: easypay5.com
SessKey: A1842D663E9A4A72XXXXXXXX303541303234373138
Content-Type: application/json
Accept: application/json
Content-Length: 64

{
  "TransID": "a88ed0e4-5a3b-11ef-b49b-46647bd59a7a",
  "CreditAmt": 5
}
200

Successfully voided the transaction

{
  "Intl_VoidCredtResult": {
    "CreditAmt": 5,
    "ErrCode": 0,
    "ErrMsg": "",
    "FunctionOk": true,
    "RespMsg": "Succesfull VOID/Credit",
    "TransID": "a88ed0e4-5a3b-11ef-b49b-46647bd59a7a",
    "TxApproved": true
  }
}