docs.emerchantpayvt.com
Open in
urlscan Pro
104.196.175.180
Public Scan
URL:
https://docs.emerchantpayvt.com/
Submission: On January 17 via api from US — Scanned from US
Submission: On January 17 via api from US — Scanned from US
Form analysis 0 forms found in the DOM
Text Content
API v2Hosted Tokenization
Digital Wallets
Google PayApple Pay
Webhooks
* Transaction processing
* Charges
* postCharge
* postTerminal Charge
* postCapture
* postAdjust
* postAdjust and capture
* postQueue
* postVerification
* Credit
* postRefund
* postCredit
* postTerminal Credit
* postVoid
* postReverse
* Surcharge
* postGet the surcharge settings for a specific payment source
* getGet the surcharge settings
* Batches and Transactions
* Batches
* getGet all batches
* getGet a single batch
* getGet transactions for a batch
* Transactions
* getGet multiple transactions
* getGet a single transaction
* Saved cards
* Saved cards
* postSave a card number
* Customers
* Customers
* getGet multiple customers
* postCreate a customer
* postCreate a customer from a transaction
* getGet a single customer
* patchUpdate a customer
* delDelete a customer
* getGet payment methods for a customer
* postCreate a payment method
* getGet recurring schedules for a customer
* postCreate a recurring schedule
* getGet transactions for a customer
* Payment Methods
* getGet all payment methods
* getGet a single payment method
* patchUpdate a payment method
* delDelete a payment method
* getGet recurring schedules for a payment method
* Recurring Schedules
* getGet all recurring schedules
* getGet a single recurring schedule
* patchUpdate a recurring schedule
* delDelete a recurring schedule
* getGet transactions for a recurring schedule
* Invoicing
* Products
* getGet products
* postCreate a new product
* getGet a single product
* patchUpdate a product
* delDelete a product
* Categories
* getGet all categories
* postCreate a new category
* getGet a single category
* patchUpdate a category
* delDelete a category
* Invoices
* getGet all invoices
* postCreate a new invoice
* getGet a single invoice
* patchUpdate an invoice
* delDelete an invoice
* postSend an existing invoice
* postCancel an existing invoice
* postReactivate a canceled invoice
* postRequest final payment for an invoice
* Apple Pay Integration
* Apple Pay Session
* postGet an Apple Pay session
API docs by Redocly
EMERCHANTPAY API V2 (2.0.0)
Welcome to the eMerchantPay gateway JSON API.
You can use our API endpoints to easily and securely charge and credit
transactions.
To use the eMerchantPay API, you must have a merchant account and source key
from the eMerchantPay gateway.
To create a source key in the gateway, navigate to Control Panel > Sources >
Create Key.
API BASE URIS:
* Production API base URI:
https://api.emerchantpayvt.com/api/v2/
* Sandbox API base URI:
https://api.sandbox.emerchantpayvt.com/api/v2/
Please use the User-Agent header to identify your software, so requests coming
from your integration can be traced.
CHARGES
CHARGE
Creates a new authorization / charge. For credit cards, by default, the
authorization will be captured into the current batch.
A charge can be from one of the following types of sources:
* Credit Card: This requires passing fields with credit card data.
* Credit Card Magstripe: This requires passing magstripe data from a swiped
credit card.
* Check / ACH
* Source: This includes charging based on a previous transaction, a stored
payment method, a token, or a nonce.
* Digital Wallet: An encrypted token containing payment data from a digital
wallet provider.
For check transactions, this request requires the Check Charge permission on the
source key. For CC transactions, if capture is false, it requires the Auth Only
permission, otherwise, it requires the Charge permission.
AUTHORIZATIONS:
BasicAuthentication
REQUEST BODY SCHEMA: APPLICATION/JSON
One of
Credit Card ChargeCredit Card Magstripe ChargeCheck / ACH ChargeSource
ChargeDigital Wallet Charge
amount
required
number [ 0.01 .. 20000000 ]
Transaction amount in USD.
If a mandatory surcharge is set by the ISO/MSP, the actual amount charged could
be different than the amount submitted in this field. The revised amounts will
be returned in the response.
The /surcharge endpoints can be used to check the surcharge before processing.
The surcharge will also be returned by the Hosted Tokenization library.
card
required
string [ 14 .. 16 ] characters ^\d+$
Card number
expiry_month
required
integer [ 1 .. 12 ]
Card expiration month. If using a card token, send any valid month.
expiry_year
required
integer [ 2020 .. 9999 ]
Card expiration year. If using a card token, send any valid year.
amount_details
object (AmountDetails)
Breakdown of the amount. These fields do not affect the actual transaction
amount and are for reporting and Level 3 only.
name
string <= 255 characters
Name on payment method (credit card or check).
transaction_details
object
Additional optional transaction details.
line_items
Array of objects (Item) non-empty
Line item details for Level 3 data.
The data will not be checked for accuracy, e.g. if the totals add up correctly.
billing_info
object (Address)
shipping_info
object (Address)
custom_fields
object (CustomFields)
ignore_duplicates
boolean
Default: false
Determines whether to override any duplicate transactions detection.
customer
object
transaction_flags
object (TransactionFlags)
These flags provide more details about the transaction. Although they are
optional, is recommended they be sent, to ensure optimal approval rates.
avs_address
string <= 255 characters
Billing address for the card.
avs_zip
string <= 50 characters
Billing zip code for the card.
While not required, this field should be populated for fraud prevention and to
obtain the best rate for E-commerce credit card transactions.
cvv2
string [ 3 .. 4 ] characters ^\d+$
Security code, otherwise known as CVC or CID. For Amex, this is the 4 digit code
on the front of the card. For other card brands, this is the 3 digit code on the
back.
While not required, this field should be populated for fraud prevention.
3d_secure
object
Data for 3D-Secure (Verified by Visa, MasterCard SecureCode, Amex SafeKey,
Discover ProtectBuy). These values come from a 3rd party 3D-Secure provider.
Note: 3D-Secure is only applicable for e-Commerce merchants. Only 3D-Secure
version 2 is supported.
capture
boolean
Default: true
Whether to capture the authorization into the current batch.
save_card
boolean
Default: false
If set to true and the transaction has been approved, the system will issue a
token for future use.
RESPONSES
200
The authorization was processed successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
415
'Content-Type' must be 'application/json'.
post/transactions/charge
Production API base URI
https://api.emerchantpayvt.com/api/v2/transactions/charge
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/transactions/charge
REQUEST SAMPLES
* Payload
Content type
application/json
Example
Credit Card ChargeCredit Card Magstripe ChargeCheck / ACH ChargeSource
ChargeDigital Wallet ChargeCredit Card Charge
Copy
Expand all Collapse all
{
* "amount": 0.01,
* "amount_details": {
* "tax": 20000000,
* "surcharge": 20000000,
* "shipping": 20000000,
* "tip": 20000000,
* "discount": 20000000
},
* "name": "string",
* "transaction_details": {
* "description": "string",
* "clerk": "string",
* "terminal": "string",
* "client_ip": "string",
* "signature": "string",
* "invoice_number": "string",
* "po_number": "string",
* "order_number": "string"
},
* "line_items": [
* {
* "sku": "string",
* "name": "string",
* "description": "string",
* "cost": 0.0001,
* "quantity": 1,
* "tax_rate": 30,
* "tax_amount": 0,
* "unit_of_measure": "str",
* "commodity_code": "stringst",
* "discount_rate": 100,
* "discount_amount": 0
}
],
* "billing_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "shipping_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "custom_fields": {
* "custom1": "string",
* "custom2": "string",
* "custom3": "string",
* "custom4": "string",
* "custom5": "string",
* "custom6": "string",
* "custom7": "string",
* "custom8": "string",
* "custom9": "string",
* "custom10": "string",
* "custom11": "string",
* "custom12": "string",
* "custom13": "string",
* "custom14": "string",
* "custom15": "string",
* "custom16": "string",
* "custom17": "string",
* "custom18": "string",
* "custom19": "string",
* "custom20": "string"
},
* "ignore_duplicates": false,
* "customer": {
* "send_receipt": false,
* "email": "string",
* "fax": "string",
* "identifier": "string",
* "customer_id": 1
},
* "transaction_flags": {
* "allow_partial_approval": false,
* "is_recurring": false,
* "is_installment": false,
* "is_customer_initiated": false,
* "cardholder_present": false,
* "card_present": false,
* "terminal": {
* "operating_environment": 0,
* "cardholder_authentication_method": "0",
* "cardholder_authentication_entity": 0,
* "print_capability": false
}
},
* "avs_address": "string",
* "avs_zip": "string",
* "expiry_month": 1,
* "expiry_year": 2020,
* "cvv2": "stri",
* "3d_secure": {
* "eci": "00",
* "cavv": "stringstringstringstringstri",
* "ds_trans_id": "084f49cd-2a97-4b13-87a7-a1bd8267cb20"
},
* "card": "stringstringst",
* "capture": true,
* "save_card": false
}
RESPONSE SAMPLES
* 200
Content type
application/json
Example
Credit Card ResponseCheck ResponseCredit Card Response
Copy
Expand all Collapse all
{
* "version": "string",
* "status": "Approved",
* "status_code": "A",
* "error_message": "string",
* "error_code": "string",
* "error_details": "string",
* "auth_amount": 0,
* "auth_code": "string",
* "reference_number": 1,
* "transaction": {
* "id": 1,
* "created_at": "2019-08-24T14:15:22Z",
* "settled_date": "2019-08-24",
* "amount_details": {
* "amount": 0.01,
* "tax": 0,
* "surcharge": 0,
* "shipping": 0,
* "tip": 0,
* "discount": 0,
* "subtotal": 0,
* "original_requested_amount": 0.01,
* "original_authorized_amount": 0.01
},
* "transaction_details": {
* "description": "string",
* "clerk": "string",
* "terminal": "string",
* "client_ip": "string",
* "signature": "string",
* "invoice_number": "string",
* "po_number": "string",
* "order_number": "string",
* "batch_id": 1,
* "source": "string",
* "username": "string",
* "type": "charge",
* "reference_number": 1
},
* "customer": {
* "identifier": "string",
* "email": "string",
* "fax": "string",
* "customer_id": 1
},
* "status_details": {
* "error_code": "string",
* "error_message": "string",
* "status": "captured"
},
* "billing_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "shipping_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "custom_fields": {
* "custom1": "string",
* "custom2": "string",
* "custom3": "string",
* "custom4": "string",
* "custom5": "string",
* "custom6": "string",
* "custom7": "string",
* "custom8": "string",
* "custom9": "string",
* "custom10": "string",
* "custom11": "string",
* "custom12": "string",
* "custom13": "string",
* "custom14": "string",
* "custom15": "string",
* "custom16": "string",
* "custom17": "string",
* "custom18": "string",
* "custom19": "string",
* "custom20": "string"
},
* "check_details": {
* "name": "string",
* "routing_number": "string",
* "account_number_last4": "string",
* "account_type": "checking",
* "sec_code": "PPD",
* "returned_at": "2019-08-24",
* "returned_code": "string",
* "returned_reason": "string"
},
* "card_details": {
* "name": "string",
* "last4": "stri",
* "expiry_month": 1,
* "expiry_year": 2020,
* "card_type": "Visa",
* "avs_street": "string",
* "avs_zip": "string",
* "auth_code": "string",
* "bin": "string",
* "avs_result": "string",
* "avs_result_code": "YYY",
* "cvv_result": "string",
* "cvv_result_code": "M",
* "cavv_result": "string",
* "cavv_result_code": "string"
}
},
* "avs_result": "string",
* "avs_result_code": "YYY",
* "cvv2_result": "string",
* "cvv2_result_code": "M",
* "card_type": "Visa",
* "last_4": "string",
* "card_ref": "string",
* "bin_type": {
* "type": "C"
}
}
TERMINAL CHARGE
By default, the authorization will be captured and included in the current
batch.
AUTHORIZATIONS:
BasicAuthentication
REQUEST BODY SCHEMA: APPLICATION/JSON
amount
required
number [ 0.01 .. 20000000 ]
Transaction amount in USD.
If a mandatory surcharge is set by the ISO/MSP, the actual amount charged could
be different than the amount submitted in this field. The revised amounts will
be returned in the response.
The /surcharge endpoints can be used to check the surcharge before processing.
The surcharge will also be returned by the Hosted Tokenization library.
terminal_id
required
string
The serial number of the terminal. This must match a terminal that is boarded in
the gateway.
amount_details
object (AmountDetails)
Breakdown of the amount. These fields do not affect the actual transaction
amount and are for reporting and Level 3 only.
name
string <= 255 characters
Name on payment method (credit card or check).
transaction_details
object
Additional optional transaction details.
line_items
Array of objects (Item) non-empty
Line item details for Level 3 data.
The data will not be checked for accuracy, e.g. if the totals add up correctly.
billing_info
object (Address)
shipping_info
object (Address)
custom_fields
object (CustomFields)
ignore_duplicates
boolean
Default: false
Determines whether to override any duplicate transactions detection.
customer
object
RESPONSES
200
The transaction was processed successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
415
'Content-Type' must be 'application/json'.
post/transactions/terminal-charge
Production API base URI
https://api.emerchantpayvt.com/api/v2/transactions/terminal-charge
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/transactions/terminal-charge
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
Expand all Collapse all
{
* "amount": 0.01,
* "amount_details": {
* "tax": 20000000,
* "surcharge": 20000000,
* "shipping": 20000000,
* "tip": 20000000,
* "discount": 20000000
},
* "name": "string",
* "transaction_details": {
* "description": "string",
* "clerk": "string",
* "terminal": "string",
* "client_ip": "string",
* "signature": "string",
* "invoice_number": "string",
* "po_number": "string",
* "order_number": "string"
},
* "line_items": [
* {
* "sku": "string",
* "name": "string",
* "description": "string",
* "cost": 0.0001,
* "quantity": 1,
* "tax_rate": 30,
* "tax_amount": 0,
* "unit_of_measure": "str",
* "commodity_code": "stringst",
* "discount_rate": 100,
* "discount_amount": 0
}
],
* "billing_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "shipping_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "custom_fields": {
* "custom1": "string",
* "custom2": "string",
* "custom3": "string",
* "custom4": "string",
* "custom5": "string",
* "custom6": "string",
* "custom7": "string",
* "custom8": "string",
* "custom9": "string",
* "custom10": "string",
* "custom11": "string",
* "custom12": "string",
* "custom13": "string",
* "custom14": "string",
* "custom15": "string",
* "custom16": "string",
* "custom17": "string",
* "custom18": "string",
* "custom19": "string",
* "custom20": "string"
},
* "ignore_duplicates": false,
* "customer": {
* "send_receipt": false,
* "email": "string",
* "fax": "string",
* "identifier": "string",
* "customer_id": 1
},
* "terminal_id": "string"
}
RESPONSE SAMPLES
* 200
Content type
application/json
Example
Credit Card ResponseCheck ResponseCredit Card Response
Copy
Expand all Collapse all
{
* "version": "string",
* "status": "Approved",
* "status_code": "A",
* "error_message": "string",
* "error_code": "string",
* "error_details": "string",
* "auth_amount": 0,
* "auth_code": "string",
* "reference_number": 1,
* "transaction": {
* "id": 1,
* "created_at": "2019-08-24T14:15:22Z",
* "settled_date": "2019-08-24",
* "amount_details": {
* "amount": 0.01,
* "tax": 0,
* "surcharge": 0,
* "shipping": 0,
* "tip": 0,
* "discount": 0,
* "subtotal": 0,
* "original_requested_amount": 0.01,
* "original_authorized_amount": 0.01
},
* "transaction_details": {
* "description": "string",
* "clerk": "string",
* "terminal": "string",
* "client_ip": "string",
* "signature": "string",
* "invoice_number": "string",
* "po_number": "string",
* "order_number": "string",
* "batch_id": 1,
* "source": "string",
* "username": "string",
* "type": "charge",
* "reference_number": 1
},
* "customer": {
* "identifier": "string",
* "email": "string",
* "fax": "string",
* "customer_id": 1
},
* "status_details": {
* "error_code": "string",
* "error_message": "string",
* "status": "captured"
},
* "billing_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "shipping_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "custom_fields": {
* "custom1": "string",
* "custom2": "string",
* "custom3": "string",
* "custom4": "string",
* "custom5": "string",
* "custom6": "string",
* "custom7": "string",
* "custom8": "string",
* "custom9": "string",
* "custom10": "string",
* "custom11": "string",
* "custom12": "string",
* "custom13": "string",
* "custom14": "string",
* "custom15": "string",
* "custom16": "string",
* "custom17": "string",
* "custom18": "string",
* "custom19": "string",
* "custom20": "string"
},
* "check_details": {
* "name": "string",
* "routing_number": "string",
* "account_number_last4": "string",
* "account_type": "checking",
* "sec_code": "PPD",
* "returned_at": "2019-08-24",
* "returned_code": "string",
* "returned_reason": "string"
},
* "card_details": {
* "name": "string",
* "last4": "stri",
* "expiry_month": 1,
* "expiry_year": 2020,
* "card_type": "Visa",
* "avs_street": "string",
* "avs_zip": "string",
* "auth_code": "string",
* "bin": "string",
* "avs_result": "string",
* "avs_result_code": "YYY",
* "cvv_result": "string",
* "cvv_result_code": "M",
* "cavv_result": "string",
* "cavv_result_code": "string"
}
},
* "avs_result": "string",
* "avs_result_code": "YYY",
* "cvv2_result": "string",
* "cvv2_result_code": "M",
* "card_type": "Visa",
* "last_4": "string",
* "card_ref": "string",
* "bin_type": {
* "type": "C"
}
}
CAPTURE
Capture an authorization into the current batch. If the authorization is already
captured, this will still return a successful response.
Only applicable to credit card authorizations.
Not supported for terminal transactions.
This request requires the Capture permission on the source key.
AUTHORIZATIONS:
BasicAuthentication
REQUEST BODY SCHEMA: APPLICATION/JSON
reference_number
required
integer >= 1
Reference number of the authorization to capture.
RESPONSES
200
The authorization was captured successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
415
'Content-Type' must be 'application/json'.
post/transactions/capture
Production API base URI
https://api.emerchantpayvt.com/api/v2/transactions/capture
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/transactions/capture
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
{
* "reference_number": 1
}
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
{
* "version": "string",
* "status": "Approved",
* "status_code": "A",
* "error_message": "string",
* "error_code": "string",
* "error_details": "string",
* "auth_amount": 0,
* "auth_code": "string"
}
ADJUST
Adjust the amount or details of a previous unsettled transaction.
This endpoint requires that the source key have a pin.
The amount of ACH and Terminal transactions cannot be adjusted, and will return
an error if a different amount is sent.
If the original transaction had amount details and this request changes the
amount, the amount_details must be resent. If only details are being adjusted
and not the amount, the amount field can be omitted.
This request requires the Adjust permission on the source key.
TSYS only supports adjusts on transactions using US or Canadian cards.
International cards must use refunds after the transaction has settled.
Adjusting a transaction to a higher amount is only permitted by the card brands
in specific scenarios. It is the the responsibility of the merchant to enforce
this.
A transaction can only be adjusted once.
AUTHORIZATIONS:
BasicAuthentication
REQUEST BODY SCHEMA: APPLICATION/JSON
reference_number
required
integer >= 1
Reference number of the transaction to adjust.
amount
number [ 0.01 .. 20000000 ]
Amount to adjust the original transaction to.
customer
object (BaseTransactionCustomer)
transaction_details
object
Additional optional transaction details.
amount_details
object (AmountDetails)
Breakdown of the amount. These fields do not affect the actual transaction
amount and are for reporting and Level 3 only.
billing_info
object (Address)
shipping_info
object (Address)
custom_fields
object (CustomFields)
line_items
Array of objects (Item) non-empty
Line item details for Level 3 data.
The data will not be checked for accuracy, e.g. if the totals add up correctly.
The new data will replace the old data.
RESPONSES
200
The authorization was adjusted successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
415
'Content-Type' must be 'application/json'.
post/transactions/adjust
Production API base URI
https://api.emerchantpayvt.com/api/v2/transactions/adjust
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/transactions/adjust
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
Expand all Collapse all
{
* "reference_number": 1,
* "amount": 0.01,
* "customer": {
* "send_receipt": false,
* "email": "string",
* "fax": "string",
* "identifier": "string"
},
* "transaction_details": {
* "description": "string",
* "clerk": "string",
* "terminal": "string",
* "client_ip": "string",
* "signature": "string",
* "invoice_number": "string",
* "po_number": "string",
* "order_number": "string"
},
* "amount_details": {
* "tax": 20000000,
* "surcharge": 20000000,
* "shipping": 20000000,
* "tip": 20000000,
* "discount": 20000000
},
* "billing_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "shipping_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "custom_fields": {
* "custom1": "string",
* "custom2": "string",
* "custom3": "string",
* "custom4": "string",
* "custom5": "string",
* "custom6": "string",
* "custom7": "string",
* "custom8": "string",
* "custom9": "string",
* "custom10": "string",
* "custom11": "string",
* "custom12": "string",
* "custom13": "string",
* "custom14": "string",
* "custom15": "string",
* "custom16": "string",
* "custom17": "string",
* "custom18": "string",
* "custom19": "string",
* "custom20": "string"
},
* "line_items": [
* {
* "sku": "string",
* "name": "string",
* "description": "string",
* "cost": 0.0001,
* "quantity": 1,
* "tax_rate": 30,
* "tax_amount": 0,
* "unit_of_measure": "str",
* "commodity_code": "stringst",
* "discount_rate": 100,
* "discount_amount": 0
}
]
}
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
{
* "version": "string",
* "status": "Approved",
* "status_code": "A",
* "error_message": "string",
* "error_code": "string",
* "error_details": "string",
* "auth_amount": 0,
* "auth_code": "string"
}
ADJUST AND CAPTURE
Adjust the amount or details of a previous unsettled transaction, and captures
it into the batch.
This endpoint requires that the source key have a pin.
This endpoint only applies to credit card transactions, and will return an error
for ACH transactions.
If the original transaction had amount details and this request changes the
amount, the amount_details must be resent. If only details are being adjusted
and not the amount, the amount field can be omitted.
This request requires the Capture permission on the source key. If the amount is
adjusted, the request will require Adjust permission as well.
TSYS only supports adjusts on transactions using US or Canadian cards.
International cards must use refunds.
Adjusting a transaction should only be done in a compliant manner and is the
responsibility of the merchant.
A transaction can only be adjusted once.
AUTHORIZATIONS:
BasicAuthentication
REQUEST BODY SCHEMA: APPLICATION/JSON
reference_number
required
integer >= 1
Reference number of the transaction to adjust.
amount
number [ 0.01 .. 20000000 ]
Amount to adjust the original transaction to.
customer
object (BaseTransactionCustomer)
transaction_details
object
Additional optional transaction details.
amount_details
object (AmountDetails)
Breakdown of the amount. These fields do not affect the actual transaction
amount and are for reporting and Level 3 only.
billing_info
object (Address)
shipping_info
object (Address)
custom_fields
object (CustomFields)
line_items
Array of objects (Item) non-empty
Line item details for Level 3 data.
The data will not be checked for accuracy, e.g. if the totals add up correctly.
The new data will replace the old data.
RESPONSES
200
The authorization was adjusted and captured successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
415
'Content-Type' must be 'application/json'.
post/transactions/adjust-capture
Production API base URI
https://api.emerchantpayvt.com/api/v2/transactions/adjust-capture
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/transactions/adjust-capture
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
Expand all Collapse all
{
* "reference_number": 1,
* "amount": 0.01,
* "customer": {
* "send_receipt": false,
* "email": "string",
* "fax": "string",
* "identifier": "string"
},
* "transaction_details": {
* "description": "string",
* "clerk": "string",
* "terminal": "string",
* "client_ip": "string",
* "signature": "string",
* "invoice_number": "string",
* "po_number": "string",
* "order_number": "string"
},
* "amount_details": {
* "tax": 20000000,
* "surcharge": 20000000,
* "shipping": 20000000,
* "tip": 20000000,
* "discount": 20000000
},
* "billing_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "shipping_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "custom_fields": {
* "custom1": "string",
* "custom2": "string",
* "custom3": "string",
* "custom4": "string",
* "custom5": "string",
* "custom6": "string",
* "custom7": "string",
* "custom8": "string",
* "custom9": "string",
* "custom10": "string",
* "custom11": "string",
* "custom12": "string",
* "custom13": "string",
* "custom14": "string",
* "custom15": "string",
* "custom16": "string",
* "custom17": "string",
* "custom18": "string",
* "custom19": "string",
* "custom20": "string"
},
* "line_items": [
* {
* "sku": "string",
* "name": "string",
* "description": "string",
* "cost": 0.0001,
* "quantity": 1,
* "tax_rate": 30,
* "tax_amount": 0,
* "unit_of_measure": "str",
* "commodity_code": "stringst",
* "discount_rate": 100,
* "discount_amount": 0
}
]
}
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
{
* "version": "string",
* "status": "Approved",
* "status_code": "A",
* "error_message": "string",
* "error_code": "string",
* "error_details": "string",
* "auth_amount": 0,
* "auth_code": "string"
}
QUEUE
Removes the authorization from the current open batch and places it into the
queue. If the authorization is already queued, this will still return a
successful response.
Only applicable to credit card authorizations. This is not supported for
terminal transactions.
This request requires the Capture permission on the source key.
AUTHORIZATIONS:
BasicAuthentication
REQUEST BODY SCHEMA: APPLICATION/JSON
reference_number
required
integer >= 1
Reference number of the authorization to queue.
RESPONSES
204
The authorization was queued successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
403
The source key does not have permissions for this endpoint. This endpoint
required the Capture permission to be set on the source key
404
The authorization was not found.
415
'Content-Type' must be 'application/json'.
422
The request could not be processed, possibly for one of the following reasons:
* The transaction was not a CC transaction or was not an authorization.
* The authorization was already settled.
* The authorization was not approved.
post/transactions/queue
Production API base URI
https://api.emerchantpayvt.com/api/v2/transactions/queue
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/transactions/queue
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
{
* "reference_number": 1
}
VERIFICATION
Verifies that a card number, and optionally AVS and/or CVV2 data, is valid.
Only applicable to credit card authorizations. This transaction will not be
saved in the gateway.
This request requires the Auth Only permission on the source key.
For Amex cards, if a CVV2 is sent and an Amex processor is available, it will be
used, regardless of processor logic. If the only CC processor is a Fiserv
(FirstData) platform, the CVV2 might be left out of the verification request
sent to the processor, since their platforms do not support CVV2 in all
situations.
AUTHORIZATIONS:
BasicAuthentication
REQUEST BODY SCHEMA: APPLICATION/JSON
One of
Credit Card Verification RequestMagstripe Verification RequestTerminal
Verification RequestSource Verification Request
card
required
string [ 14 .. 16 ] characters ^\d+$
Card number
expiry_month
required
integer [ 1 .. 12 ]
Card expiration month. If using a card token, send any valid month.
expiry_year
required
integer [ 2020 .. 9999 ]
Card expiration year. If using a card token, send any valid year.
avs_address
string <= 255 characters
Billing address for the card.
avs_zip
string <= 50 characters
Billing zip code for the card.
While not required, this field should be populated for fraud prevention and to
obtain the best rate for E-commerce credit card transactions.
name
string <= 255 characters
Name on card
transaction_details
object (BaseTransactionDetails)
Additional optional transaction details.
save_card
boolean
Default: false
If set to true and the transaction has been approved, the system will issue a
token for future use.
transaction_flags
object (TransactionFlags)
These flags provide more details about the transaction. Although they are
optional, is recommended they be sent, to ensure optimal approval rates.
cvv2
string [ 3 .. 4 ] characters ^\d+$
Security code, otherwise known as CVC or CID. For Amex, this is the 4 digit code
on the front of the card. For other card brands, this is the 3 digit code on the
back.
While not required, this field should be populated for fraud prevention.
3d_secure
object
Data for 3D-Secure (Verified by Visa, MasterCard SecureCode, Amex SafeKey,
Discover ProtectBuy). These values come from a 3rd party 3D-Secure provider.
Note: 3D-Secure is only applicable for e-Commerce merchants. Only 3D-Secure
version 2 is supported.
RESPONSES
200
The verification request was processed successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
415
'Content-Type' must be 'application/json'.
post/transactions/verify
Production API base URI
https://api.emerchantpayvt.com/api/v2/transactions/verify
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/transactions/verify
REQUEST SAMPLES
* Payload
Content type
application/json
Example
Credit Card Verification RequestMagstripe Verification RequestTerminal
Verification RequestSource Verification RequestCredit Card Verification Request
Copy
Expand all Collapse all
{
* "avs_address": "string",
* "avs_zip": "string",
* "name": "string",
* "transaction_details": {
* "description": "string",
* "clerk": "string",
* "terminal": "string",
* "client_ip": "string",
* "signature": "string"
},
* "save_card": false,
* "transaction_flags": {
* "allow_partial_approval": false,
* "is_recurring": false,
* "is_installment": false,
* "is_customer_initiated": false,
* "cardholder_present": false,
* "card_present": false,
* "terminal": {
* "operating_environment": 0,
* "cardholder_authentication_method": "0",
* "cardholder_authentication_entity": 0,
* "print_capability": false
}
},
* "expiry_month": 1,
* "expiry_year": 2020,
* "cvv2": "stri",
* "3d_secure": {
* "eci": "00",
* "cavv": "stringstringstringstringstri",
* "ds_trans_id": "084f49cd-2a97-4b13-87a7-a1bd8267cb20"
},
* "card": "stringstringst"
}
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
Expand all Collapse all
{
* "version": "string",
* "status": "Approved",
* "status_code": "A",
* "error_message": "string",
* "error_code": "string",
* "error_details": "string",
* "avs_result": "string",
* "avs_result_code": "YYY",
* "cvv2_result": "string",
* "cvv2_result_code": "M",
* "card_type": "string",
* "last_4": "string",
* "card_ref": "string",
* "bin_type": {
* "type": "C"
},
* "transaction": {
* "id": 1,
* "created_at": "2019-08-24T14:15:22Z",
* "settled_date": "2019-08-24",
* "amount_details": {
* "amount": 0.01,
* "tax": 0,
* "surcharge": 0,
* "shipping": 0,
* "tip": 0,
* "discount": 0,
* "subtotal": 0,
* "original_requested_amount": 0.01,
* "original_authorized_amount": 0.01
},
* "transaction_details": {
* "description": "string",
* "clerk": "string",
* "terminal": "string",
* "client_ip": "string",
* "signature": "string",
* "invoice_number": "string",
* "po_number": "string",
* "order_number": "string",
* "batch_id": 1,
* "source": "string",
* "username": "string",
* "type": "charge",
* "reference_number": 1
},
* "customer": {
* "identifier": "string",
* "email": "string",
* "fax": "string",
* "customer_id": 1
},
* "status_details": {
* "error_code": "string",
* "error_message": "string",
* "status": "captured"
},
* "billing_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "shipping_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "custom_fields": {
* "custom1": "string",
* "custom2": "string",
* "custom3": "string",
* "custom4": "string",
* "custom5": "string",
* "custom6": "string",
* "custom7": "string",
* "custom8": "string",
* "custom9": "string",
* "custom10": "string",
* "custom11": "string",
* "custom12": "string",
* "custom13": "string",
* "custom14": "string",
* "custom15": "string",
* "custom16": "string",
* "custom17": "string",
* "custom18": "string",
* "custom19": "string",
* "custom20": "string"
},
* "card_details": {
* "name": "string",
* "last4": "stri",
* "expiry_month": 1,
* "expiry_year": 2020,
* "card_type": "Visa",
* "avs_street": "string",
* "avs_zip": "string",
* "auth_code": "string",
* "bin": "string",
* "avs_result": "string",
* "avs_result_code": "YYY",
* "cvv_result": "string",
* "cvv_result_code": "M",
* "cavv_result": "string",
* "cavv_result_code": "string"
}
}
}
CREDIT
REFUND
Refund a previously settled charge. An error will be returned if the original
transaction has not yet settled.
This request requires the Refund permission on the source key for CC
transactions, and Check Refund for checks.
ACH transactions can only be refunded after 5 business days have passed since
the transaction was processed.
Terminals with connected refunds will behave as matched refunds.
AUTHORIZATIONS:
BasicAuthentication
REQUEST BODY SCHEMA: APPLICATION/JSON
reference_number
required
integer >= 1
Reference number of the transaction to refund.
terminal_id
string
The serial number of the terminal. This must match a terminal that is boarded in
the gateway.
By default the refund transaction will process on the terminal that the original
transaction was processed on. To specify a different terminal, this field can be
set.
amount
number [ 0.01 .. 20000000 ]
Amount of original transaction to refund. Omit this field to refund the full
amount.
cvv2
string [ 3 .. 4 ] characters ^\d+$
Security code, otherwise known as CVC or CID. For Amex, this is the 4 digit code
on the front of the card. For other card brands, this is the 3 digit code on the
back.
While not required, this field should be populated for fraud prevention.
customer
object (BaseTransactionCustomer)
transaction_details
object (BaseTransactionDetails)
Additional optional transaction details.
transaction_flags
object (TransactionFlags)
These flags provide more details about the transaction. Although they are
optional, is recommended they be sent, to ensure optimal approval rates.
custom_fields
object (CustomFields)
RESPONSES
200
The refund was processed successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
415
'Content-Type' must be 'application/json'.
post/transactions/refund
Production API base URI
https://api.emerchantpayvt.com/api/v2/transactions/refund
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/transactions/refund
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
Expand all Collapse all
{
* "reference_number": 1,
* "terminal_id": "string",
* "amount": 0.01,
* "cvv2": "stri",
* "customer": {
* "send_receipt": false,
* "email": "string",
* "fax": "string",
* "identifier": "string"
},
* "transaction_details": {
* "description": "string",
* "clerk": "string",
* "terminal": "string",
* "client_ip": "string",
* "signature": "string"
},
* "transaction_flags": {
* "allow_partial_approval": false,
* "is_recurring": false,
* "is_installment": false,
* "is_customer_initiated": false,
* "cardholder_present": false,
* "card_present": false,
* "terminal": {
* "operating_environment": 0,
* "cardholder_authentication_method": "0",
* "cardholder_authentication_entity": 0,
* "print_capability": false
}
},
* "custom_fields": {
* "custom1": "string",
* "custom2": "string",
* "custom3": "string",
* "custom4": "string",
* "custom5": "string",
* "custom6": "string",
* "custom7": "string",
* "custom8": "string",
* "custom9": "string",
* "custom10": "string",
* "custom11": "string",
* "custom12": "string",
* "custom13": "string",
* "custom14": "string",
* "custom15": "string",
* "custom16": "string",
* "custom17": "string",
* "custom18": "string",
* "custom19": "string",
* "custom20": "string"
}
}
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
{
* "version": "string",
* "status": "Approved",
* "status_code": "A",
* "error_message": "string",
* "error_code": "string",
* "error_details": "string",
* "reference_number": 1
}
CREDIT
Credit money back to a payment method.
A credit can be to one of 3 different types of sources:
* Credit Card: This requires passing fields with credit card data.
* Credit Card Magstripe: This requires passing magstripe data from a swiped
credit card.
* Check
* Source: This includes crediting based on a previous transaction, a stored
payment method, or a token.
This feature must be enabled by the ISO/MSP. It requires the Refund permission
on the source key for CC transactions, and Check Refund for checks.
AUTHORIZATIONS:
BasicAuthentication
REQUEST BODY SCHEMA: APPLICATION/JSON
One of
Credit with Credit Card NumberCredit with MagstripeCheck / ACH CreditSource
Credit
card
required
string [ 14 .. 16 ] characters ^\d+$
Card number
expiry_month
required
integer [ 1 .. 12 ]
Card expiration month. If using a card token, send any valid month.
expiry_year
required
integer [ 2020 .. 9999 ]
Card expiration year. If using a card token, send any valid year.
amount
required
number [ 0.01 .. 20000000 ]
Amount to credit.
avs_address
string <= 255 characters
Billing address for the card.
avs_zip
string <= 50 characters
Billing zip code for the card.
While not required, this field should be populated for fraud prevention and to
obtain the best rate for E-commerce credit card transactions.
cvv2
string [ 3 .. 4 ] characters ^\d+$
Security code, otherwise known as CVC or CID. For Amex, this is the 4 digit code
on the front of the card. For other card brands, this is the 3 digit code on the
back.
While not required, this field should be populated for fraud prevention.
name
string <= 255 characters
Name on card
customer
object
transaction_details
object
Additional optional transaction details.
transaction_flags
object (TransactionFlags)
These flags provide more details about the transaction. Although they are
optional, is recommended they be sent, to ensure optimal approval rates.
custom_fields
object (CustomFields)
RESPONSES
200
The credit was processed successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
415
'Content-Type' must be 'application/json'.
post/transactions/credit
Production API base URI
https://api.emerchantpayvt.com/api/v2/transactions/credit
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/transactions/credit
REQUEST SAMPLES
* Payload
Content type
application/json
Example
Credit with Credit Card NumberCredit with MagstripeCheck / ACH CreditSource
CreditCredit with Credit Card Number
Copy
Expand all Collapse all
{
* "avs_address": "string",
* "avs_zip": "string",
* "expiry_month": 1,
* "expiry_year": 2020,
* "cvv2": "stri",
* "name": "string",
* "card": "stringstringst",
* "amount": 0.01,
* "customer": {
* "send_receipt": false,
* "email": "string",
* "fax": "string",
* "identifier": "string",
* "customer_id": 1
},
* "transaction_details": {
* "description": "string",
* "clerk": "string",
* "terminal": "string",
* "client_ip": "string",
* "signature": "string",
* "invoice_number": "string",
* "po_number": "string",
* "order_number": "string"
},
* "transaction_flags": {
* "allow_partial_approval": false,
* "is_recurring": false,
* "is_installment": false,
* "is_customer_initiated": false,
* "cardholder_present": false,
* "card_present": false,
* "terminal": {
* "operating_environment": 0,
* "cardholder_authentication_method": "0",
* "cardholder_authentication_entity": 0,
* "print_capability": false
}
},
* "custom_fields": {
* "custom1": "string",
* "custom2": "string",
* "custom3": "string",
* "custom4": "string",
* "custom5": "string",
* "custom6": "string",
* "custom7": "string",
* "custom8": "string",
* "custom9": "string",
* "custom10": "string",
* "custom11": "string",
* "custom12": "string",
* "custom13": "string",
* "custom14": "string",
* "custom15": "string",
* "custom16": "string",
* "custom17": "string",
* "custom18": "string",
* "custom19": "string",
* "custom20": "string"
}
}
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
{
* "version": "string",
* "status": "Approved",
* "status_code": "A",
* "error_message": "string",
* "error_code": "string",
* "error_details": "string",
* "reference_number": 1
}
TERMINAL CREDIT
Credit money back to a payment method.
This feature must be enabled by the ISO/MSP. It requires the Refund permission
on the source key for CC transactions, and Check Refund for checks.
AUTHORIZATIONS:
BasicAuthentication
REQUEST BODY SCHEMA: APPLICATION/JSON
terminal_id
required
string
The serial number of the terminal. This must match a terminal that is boarded in
the gateway.
amount
required
number [ 0.01 .. 20000000 ]
Amount to credit.
customer
object
transaction_details
object
Additional optional transaction details.
custom_fields
object (CustomFields)
RESPONSES
200
The credit was processed successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
415
'Content-Type' must be 'application/json'.
post/transactions/terminal-credit
Production API base URI
https://api.emerchantpayvt.com/api/v2/transactions/terminal-credit
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/transactions/terminal-credit
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
Expand all Collapse all
{
* "terminal_id": "string",
* "amount": 0.01,
* "customer": {
* "send_receipt": false,
* "email": "string",
* "fax": "string",
* "identifier": "string",
* "customer_id": 1
},
* "transaction_details": {
* "description": "string",
* "clerk": "string",
* "terminal": "string",
* "client_ip": "string",
* "signature": "string",
* "invoice_number": "string",
* "po_number": "string",
* "order_number": "string"
},
* "custom_fields": {
* "custom1": "string",
* "custom2": "string",
* "custom3": "string",
* "custom4": "string",
* "custom5": "string",
* "custom6": "string",
* "custom7": "string",
* "custom8": "string",
* "custom9": "string",
* "custom10": "string",
* "custom11": "string",
* "custom12": "string",
* "custom13": "string",
* "custom14": "string",
* "custom15": "string",
* "custom16": "string",
* "custom17": "string",
* "custom18": "string",
* "custom19": "string",
* "custom20": "string"
}
}
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
{
* "version": "string",
* "status": "Approved",
* "status_code": "A",
* "error_message": "string",
* "error_code": "string",
* "error_details": "string",
* "reference_number": 1
}
VOID
Void a previously unsettled charge. An error will be returned if the original
transaction has already been settled.
This request requires the Void permission on the source key for CC transactions,
and Check Void for checks.
ACH transactions can only be voided until 1am Eastern Time.
FirstData terminal transactions are host capture and can only be voided within
25 minutes of the transaction.
TSYS only supports voids on transactions using US or Canadian cards.
International cards must use refunds.
AUTHORIZATIONS:
BasicAuthentication
REQUEST BODY SCHEMA: APPLICATION/JSON
reference_number
required
integer >= 1
Reference number of the transaction to void.
customer
object (BaseTransactionCustomer)
transaction_details
object (BaseTransactionDetails)
Additional optional transaction details.
RESPONSES
200
The void was processed successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
415
'Content-Type' must be 'application/json'.
post/transactions/void
Production API base URI
https://api.emerchantpayvt.com/api/v2/transactions/void
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/transactions/void
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
Expand all Collapse all
{
* "reference_number": 1,
* "customer": {
* "send_receipt": false,
* "email": "string",
* "fax": "string",
* "identifier": "string"
},
* "transaction_details": {
* "description": "string",
* "clerk": "string",
* "terminal": "string",
* "client_ip": "string",
* "signature": "string"
}
}
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
{
* "version": "string",
* "status": "Approved",
* "status_code": "A",
* "error_message": "string",
* "error_code": "string",
* "error_details": "string"
}
REVERSE
This is a convenience method to completely or partially reverse a previous
transaction, regardless of the state which it's currently in. It combines the
functionality of the /transactions/adjust, /transactions/void, and
/transactions/refund endpoints.
* If no amount is sent:
* If the transaction is unsettled, it will be voided.
* If the transaction is settled, it will be completely refunded.
* If an amount is sent:
* If the transaction is unsettled, it will be adjusted by reducing it by the
amount passed (amount is the amount to reduce it by, not the new amount).
If the amount is the full amount of the authorization, it will be voided.
* If the transaction is settled, it will be refunded for the amount sent.
ACH transactions can only be voided until 1am Eastern Time the night after the
transaction was processed, and can only be refunded after 5 business days have
passed since the transaction was processed.
First Data terminal transactions can only be voided within 25 minutes of the
transaction. After that point it will be run as a refund/credit regardless if
the transaction is settled.
Terminal transactions cannot be adjusted, and will always run as a refund if a
different amount is sent regardless if the transaction is settled.
ACH transactions cannot be adjusted, and will return an error if a different
amount is sent and they are unsettled.
This endpoint requires that the source key have a pin, and requires the
following permissions on the source key:
* For CC transactions: Charge, Void, and Refund.
* For checks: Check Void and Check Refund.
TSYS only supports voids/adjusts on transactions using US or Canadian cards.
International cards must use refunds.
Terminal full reversals that are processed on a different terminal (by
specifying terminal_id) will be processed as a refund, instead of an void.
Terminals with connected refunds will behave as matched refunds.
AUTHORIZATIONS:
BasicAuthentication
REQUEST BODY SCHEMA: APPLICATION/JSON
reference_number
required
integer >= 1
Reference number of the transaction to reverse.
terminal_id
string
The serial number of the terminal. This must match a terminal that is boarded in
the gateway.
By default the reversal transaction will process on the terminal that the
original transaction was processed on. To specify a different terminal, this
field can be set.
If a different terminal is set, a void will run as a refund.
amount
number [ 0.01 .. 20000000 ]
Amount of original transaction to reverse.
customer
object (BaseTransactionCustomer)
transaction_details
object (BaseTransactionDetails)
Additional optional transaction details.
RESPONSES
200
The authorization was reversed successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
415
'Content-Type' must be 'application/json'.
post/transactions/reversal
Production API base URI
https://api.emerchantpayvt.com/api/v2/transactions/reversal
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/transactions/reversal
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
Expand all Collapse all
{
* "reference_number": 1,
* "terminal_id": "string",
* "amount": 0.01,
* "customer": {
* "send_receipt": false,
* "email": "string",
* "fax": "string",
* "identifier": "string"
},
* "transaction_details": {
* "description": "string",
* "clerk": "string",
* "terminal": "string",
* "client_ip": "string",
* "signature": "string"
}
}
RESPONSE SAMPLES
* 200
Content type
application/json
Example
Response for VoidResponse for RefundResponse for AdjustResponse for Void
Copy
{
* "version": "string",
* "status": "Approved",
* "status_code": "A",
* "error_message": "string",
* "error_code": "string",
* "error_details": "string",
* "type": "void"
}
SURCHARGE
GET THE SURCHARGE SETTINGS FOR A SPECIFIC PAYMENT SOURCE
Returns the surcharge that will be automatically applied when processing a
transaction using the specified payment source (e.g. a card number).
AUTHORIZATIONS:
BasicAuthentication
REQUEST BODY SCHEMA: APPLICATION/JSON
source_type
required
string
Enum: "card" "tkn" "pm" "ref"
* card: Card number
* tkn: Token
* pm: Payment method ID
* ref: Reference number
source
required
string <= 16 characters [A-Za-z0-9]+
The source to return the surcharge details for. This can be a card, a token, a
payment method ID or the reference number of a previous transaction.
For a source type of card, this does not need to be a full card number. However,
the more digits that are sent, the more likely a match will be found.
RESPONSES
200
The surcharge details were returned successfully.
400
The request was invalid.
401
Credentials are missing or invalid.
404
Surcharge details were not found.
post/surcharge
Production API base URI
https://api.emerchantpayvt.com/api/v2/surcharge
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/surcharge
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
{
* "source_type": "card",
* "source": "string"
}
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
Expand all Collapse all
{
* "surcharge": {
* "type": "percent",
* "value": 0
},
* "bin_type": "C",
* "payment_type": "card"
}
GET THE SURCHARGE SETTINGS
AUTHORIZATIONS:
BasicAuthentication
RESPONSES
200
The surcharge details were returned successfully.
400
The request was invalid.
401
Credentials are missing or invalid.
404
Surcharge details were not found.
get/surcharge
Production API base URI
https://api.emerchantpayvt.com/api/v2/surcharge
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/surcharge
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
Expand all Collapse all
{
* "card": {
* "type": "percent",
* "value": 0
},
* "check": {
* "type": "percent",
* "value": 0
}
}
BATCHES
GET ALL BATCHES
Returns a paginated list of all batches.
AUTHORIZATIONS:
BasicAuthentication
QUERY PARAMETERS
order
string
Default: "asc"
Enum: "asc" "desc"
The sort order.
status
string
Enum: "open" "closed"
The status of the batch.
date_from
integer or string
The earliest date to search. This will be rounded down to the beginning of the
day in UTC.
date_to
integer or string
The latest date to search. This will be rounded up to the end of the day in UTC.
limit
integer [ 1 .. 100 ]
Default: 10
The maximum number of results to return.
offset
integer >= 0
The 0-based offset to start from.
RESPONSES
200
The batches were retrieved successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
get/batches
Production API base URI
https://api.emerchantpayvt.com/api/v2/batches
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/batches
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
Expand all Collapse all
[
* {
* "id": 1,
* "opened_at": null,
* "auto_close_date": null,
* "closed_at": null,
* "platform": "north",
* "charges_sum": 0.01,
* "charges_count": 1,
* "credits_sum": 0.01,
* "credits_count": 1,
* "transactions_count": 1
}
]
GET A SINGLE BATCH
Get a single batch by batch ID.
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The batch ID.
RESPONSES
200
The batch was retrieved successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
404
The batch was not found.
get/batches/{id}
Production API base URI
https://api.emerchantpayvt.com/api/v2/batches/{id}
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/batches/{id}
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
{
* "id": 1,
* "opened_at": null,
* "auto_close_date": null,
* "closed_at": null,
* "platform": "north",
* "charges_sum": 0.01,
* "charges_count": 1,
* "credits_sum": 0.01,
* "credits_count": 1,
* "transactions_count": 1
}
GET TRANSACTIONS FOR A BATCH
Get the transactions in the specified batch.
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The batch ID.
QUERY PARAMETERS
order
string
Default: "asc"
Enum: "asc" "desc"
The sort order.
status
Array of strings
Items Enum: "captured" "pending" "reserve" "originated" "returned" "cancelled"
"queued" "declined" "error" "settled" "voided" "approved" "blocked" "expired"
The transaction status(es) to filter by. Multiple values can be sent, separated
by commas.
payment_type
Array of strings
Items Enum: "credit_card" "check"
The transaction payment type(s) to filter by. Multiple values can be sent,
separated by commas.
settled_date
string <date>
The settled date in UTC to filter for. This will exclude transactions processed
more than 30 days before the specified settlement date, regardless of the
date_from query parameter.
date_field
string
Default: "created_at"
Enum: "settled_at" "created_at"
The date event to filter by. This field only has an effect when combined with
date_from and date_to filters
date_from
integer or string
The earliest date to search. This will be rounded down to the beginning of the
day in UTC.
date_to
integer or string
The latest date to search. This will be rounded up to the end of the day in UTC.
limit
integer [ 1 .. 100 ]
Default: 10
The maximum number of results to return.
offset
integer >= 0
The 0-based offset to start from.
RESPONSES
200
The transactions were retrieved successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
404
The batch was not found.
get/batches/{id}/transactions
Production API base URI
https://api.emerchantpayvt.com/api/v2/batches/{id}/transactions
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/batches/{id}/transactions
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
Expand all Collapse all
[
* {
* "id": 1,
* "created_at": "2019-08-24T14:15:22Z",
* "settled_date": "2019-08-24",
* "amount_details": {
* "amount": 0.01,
* "tax": 0,
* "surcharge": 0,
* "shipping": 0,
* "tip": 0,
* "discount": 0,
* "subtotal": 0,
* "original_requested_amount": 0.01,
* "original_authorized_amount": 0.01
},
* "transaction_details": {
* "description": "string",
* "clerk": "string",
* "terminal": "string",
* "client_ip": "string",
* "signature": "string",
* "invoice_number": "string",
* "po_number": "string",
* "order_number": "string",
* "batch_id": 1,
* "source": "string",
* "username": "string",
* "type": "charge",
* "reference_number": 1
},
* "customer": {
* "identifier": "string",
* "email": "string",
* "fax": "string",
* "customer_id": 1
},
* "status_details": {
* "error_code": "string",
* "error_message": "string",
* "status": "captured"
},
* "billing_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "shipping_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "custom_fields": {
* "custom1": "string",
* "custom2": "string",
* "custom3": "string",
* "custom4": "string",
* "custom5": "string",
* "custom6": "string",
* "custom7": "string",
* "custom8": "string",
* "custom9": "string",
* "custom10": "string",
* "custom11": "string",
* "custom12": "string",
* "custom13": "string",
* "custom14": "string",
* "custom15": "string",
* "custom16": "string",
* "custom17": "string",
* "custom18": "string",
* "custom19": "string",
* "custom20": "string"
},
* "card_details": {
* "name": "string",
* "last4": "stri",
* "expiry_month": 1,
* "expiry_year": 2020,
* "card_type": "Visa",
* "avs_street": "string",
* "avs_zip": "string",
* "auth_code": "string",
* "bin": "string",
* "avs_result": "string",
* "avs_result_code": "YYY",
* "cvv_result": "string",
* "cvv_result_code": "M",
* "cavv_result": "string",
* "cavv_result_code": "string"
}
}
]
TRANSACTIONS
GET MULTIPLE TRANSACTIONS
Returns an array of transactions
AUTHORIZATIONS:
BasicAuthentication
QUERY PARAMETERS
order
string
Default: "asc"
Enum: "asc" "desc"
The sort order.
status
Array of strings
Items Enum: "captured" "pending" "reserve" "originated" "returned" "cancelled"
"queued" "declined" "error" "settled" "voided" "approved" "blocked" "expired"
The transaction status(es) to filter by. Multiple values can be sent, separated
by commas.
payment_type
Array of strings
Items Enum: "credit_card" "check"
The transaction payment type(s) to filter by. Multiple values can be sent,
separated by commas.
settled_date
string <date>
The settled date in UTC to filter for. This will exclude transactions processed
more than 30 days before the specified settlement date, regardless of the
date_from query parameter.
date_field
string
Default: "created_at"
Enum: "settled_at" "created_at"
The date event to filter by. This field only has an effect when combined with
date_from and date_to filters
date_from
integer or string
The earliest date to search. This will be rounded down to the beginning of the
day in UTC.
date_to
integer or string
The latest date to search. This will be rounded up to the end of the day in UTC.
limit
integer [ 1 .. 100 ]
Default: 10
The maximum number of results to return.
offset
integer >= 0
The 0-based offset to start from.
RESPONSES
200
The transactions were returned successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
get/transactions
Production API base URI
https://api.emerchantpayvt.com/api/v2/transactions
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/transactions
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
Expand all Collapse all
[
* {
* "id": 1,
* "created_at": "2019-08-24T14:15:22Z",
* "settled_date": "2019-08-24",
* "amount_details": {
* "amount": 0.01,
* "tax": 0,
* "surcharge": 0,
* "shipping": 0,
* "tip": 0,
* "discount": 0,
* "subtotal": 0,
* "original_requested_amount": 0.01,
* "original_authorized_amount": 0.01
},
* "transaction_details": {
* "description": "string",
* "clerk": "string",
* "terminal": "string",
* "client_ip": "string",
* "signature": "string",
* "invoice_number": "string",
* "po_number": "string",
* "order_number": "string",
* "batch_id": 1,
* "source": "string",
* "username": "string",
* "type": "charge",
* "reference_number": 1
},
* "customer": {
* "identifier": "string",
* "email": "string",
* "fax": "string",
* "customer_id": 1
},
* "status_details": {
* "error_code": "string",
* "error_message": "string",
* "status": "captured"
},
* "billing_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "shipping_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "custom_fields": {
* "custom1": "string",
* "custom2": "string",
* "custom3": "string",
* "custom4": "string",
* "custom5": "string",
* "custom6": "string",
* "custom7": "string",
* "custom8": "string",
* "custom9": "string",
* "custom10": "string",
* "custom11": "string",
* "custom12": "string",
* "custom13": "string",
* "custom14": "string",
* "custom15": "string",
* "custom16": "string",
* "custom17": "string",
* "custom18": "string",
* "custom19": "string",
* "custom20": "string"
},
* "card_details": {
* "name": "string",
* "last4": "stri",
* "expiry_month": 1,
* "expiry_year": 2020,
* "card_type": "Visa",
* "avs_street": "string",
* "avs_zip": "string",
* "auth_code": "string",
* "bin": "string",
* "avs_result": "string",
* "avs_result_code": "YYY",
* "cvv_result": "string",
* "cvv_result_code": "M",
* "cavv_result": "string",
* "cavv_result_code": "string"
}
}
]
GET A SINGLE TRANSACTION
Returns a single transaction by reference number
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The transaction ID.
RESPONSES
200
The transaction was returned successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
404
The transaction was not found.
get/transactions/{id}
Production API base URI
https://api.emerchantpayvt.com/api/v2/transactions/{id}
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/transactions/{id}
RESPONSE SAMPLES
* 200
Content type
application/json
Example
Credit Card TransactionCheck TransactionCredit Card Transaction
Copy
Expand all Collapse all
{
* "id": 1,
* "created_at": "2019-08-24T14:15:22Z",
* "settled_date": "2019-08-24",
* "amount_details": {
* "amount": 0.01,
* "tax": 0,
* "surcharge": 0,
* "shipping": 0,
* "tip": 0,
* "discount": 0,
* "subtotal": 0,
* "original_requested_amount": 0.01,
* "original_authorized_amount": 0.01
},
* "transaction_details": {
* "description": "string",
* "clerk": "string",
* "terminal": "string",
* "client_ip": "string",
* "signature": "string",
* "invoice_number": "string",
* "po_number": "string",
* "order_number": "string",
* "batch_id": 1,
* "source": "string",
* "username": "string",
* "type": "charge",
* "reference_number": 1
},
* "customer": {
* "identifier": "string",
* "email": "string",
* "fax": "string",
* "customer_id": 1
},
* "status_details": {
* "error_code": "string",
* "error_message": "string",
* "status": "captured"
},
* "billing_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "shipping_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "custom_fields": {
* "custom1": "string",
* "custom2": "string",
* "custom3": "string",
* "custom4": "string",
* "custom5": "string",
* "custom6": "string",
* "custom7": "string",
* "custom8": "string",
* "custom9": "string",
* "custom10": "string",
* "custom11": "string",
* "custom12": "string",
* "custom13": "string",
* "custom14": "string",
* "custom15": "string",
* "custom16": "string",
* "custom17": "string",
* "custom18": "string",
* "custom19": "string",
* "custom20": "string"
},
* "card_details": {
* "name": "string",
* "last4": "stri",
* "expiry_month": 1,
* "expiry_year": 2020,
* "card_type": "Visa",
* "avs_street": "string",
* "avs_zip": "string",
* "auth_code": "string",
* "bin": "string",
* "avs_result": "string",
* "avs_result_code": "YYY",
* "cvv_result": "string",
* "cvv_result_code": "M",
* "cavv_result": "string",
* "cavv_result_code": "string"
}
}
SAVED CARDS
SAVE A CARD NUMBER
Save a card number for future use. A token will be returned, which can be used
later in place of a card number.
This will not verify that the card is valid. It is recommended to instead use a
Verification request, and set the save_card property to true. This will run a
Verification transaction to verify that the card is valid, and return a token in
the response.
AUTHORIZATIONS:
BasicAuthentication
REQUEST BODY SCHEMA: APPLICATION/JSON
expiry_month
required
integer [ 1 .. 12 ]
Card expiration month
expiry_year
required
integer [ 2020 .. 9999 ]
Card expiration year
card
required
string [ 14 .. 16 ] characters ^\d+$
Card number
RESPONSES
200
The card was saved successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
415
'Content-Type' must be 'application/json'.
post/saved-cards
Production API base URI
https://api.emerchantpayvt.com/api/v2/saved-cards
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/saved-cards
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
{
* "expiry_month": 1,
* "expiry_year": 2020,
* "card": "stringstringst"
}
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
{
* "cardRef": "stringstringstri"
}
CUSTOMERS
GET MULTIPLE CUSTOMERS
Returns an array of customers
AUTHORIZATIONS:
BasicAuthentication
QUERY PARAMETERS
order
string
Default: "asc"
Enum: "asc" "desc"
The sort order.
limit
integer [ 1 .. 100 ]
Default: 10
The maximum number of results to return.
offset
integer >= 0
The 0-based offset to start from.
active
boolean
The status of the customer.
customer_number
string
The customer_number of the customer.
RESPONSES
200
The customers were returned successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
get/customers
Production API base URI
https://api.emerchantpayvt.com/api/v2/customers
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/customers
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
Expand all Collapse all
[
* {
* "identifier": "string",
* "customer_number": "string",
* "first_name": "string",
* "last_name": "string",
* "email": "string",
* "website": "string",
* "phone": "string",
* "alternate_phone": "string",
* "billing_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "shipping_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "active": true,
* "id": 1
}
]
CREATE A CUSTOMER
AUTHORIZATIONS:
BasicAuthentication
REQUEST BODY SCHEMA: APPLICATION/JSON
identifier
required
string <= 255 characters
Something that identifies the customer, e.g. the customer's name or company.
customer_number
string <= 255 characters
A custom identifier.
first_name
string <= 255 characters
last_name
string <= 255 characters
email
string <= 255 characters
website
string <= 255 characters
phone
string <= 255 characters
alternate_phone
string <= 255 characters
billing_info
object (Address)
shipping_info
object (Address)
active
boolean
Default: true
RESPONSES
201
The customer was created successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
415
'Content-Type' must be 'application/json'.
post/customers
Production API base URI
https://api.emerchantpayvt.com/api/v2/customers
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/customers
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
Expand all Collapse all
{
* "identifier": "string",
* "customer_number": "string",
* "first_name": "string",
* "last_name": "string",
* "email": "string",
* "website": "string",
* "phone": "string",
* "alternate_phone": "string",
* "billing_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "shipping_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "active": true
}
RESPONSE SAMPLES
* 201
Content type
application/json
Copy
Expand all Collapse all
{
* "identifier": "string",
* "customer_number": "string",
* "first_name": "string",
* "last_name": "string",
* "email": "string",
* "website": "string",
* "phone": "string",
* "alternate_phone": "string",
* "billing_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "shipping_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "active": true,
* "id": 1
}
CREATE A CUSTOMER FROM A TRANSACTION
This will create a new customer using the information from the referenced
transaction. A payment method can subsequently be created using the transaction
as the source. Any field provided in the body will override the data from the
transaction. A new customer will be created even if the transaction is already
linked to an existing customer. If the transaction is not already linked to a
customer, it will be linked to the newly created customer.
AUTHORIZATIONS:
BasicAuthentication
REQUEST BODY SCHEMA: APPLICATION/JSON
reference_number
required
integer >= 1
Reference number for the transaction.
identifier
string <= 255 characters
Something that identifies the customer, e.g. the customer's name or company.
customer_number
string <= 255 characters
A custom identifier.
first_name
string <= 255 characters
last_name
string <= 255 characters
email
string <= 255 characters
website
string <= 255 characters
phone
string <= 255 characters
alternate_phone
string <= 255 characters
billing_info
object (Address)
shipping_info
object (Address)
active
boolean
Default: true
RESPONSES
201
The customer was created successfully.
400
The body was invalid.
401
Credentials are missing or invalid.
404
The transaction was not found.
415
'Content-Type' must be 'application/json'.
post/customers/create-from-transaction
Production API base URI
https://api.emerchantpayvt.com/api/v2/customers/create-from-transaction
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/customers/create-from-transaction
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
Expand all Collapse all
{
* "identifier": "string",
* "customer_number": "string",
* "first_name": "string",
* "last_name": "string",
* "email": "string",
* "website": "string",
* "phone": "string",
* "alternate_phone": "string",
* "billing_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "shipping_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "active": true,
* "reference_number": 1
}
RESPONSE SAMPLES
* 201
Content type
application/json
Copy
Expand all Collapse all
{
* "identifier": "string",
* "customer_number": "string",
* "first_name": "string",
* "last_name": "string",
* "email": "string",
* "website": "string",
* "phone": "string",
* "alternate_phone": "string",
* "billing_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "shipping_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "active": true,
* "id": 1
}
GET A SINGLE CUSTOMER
Returns a single customers by ID number
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The customer ID.
RESPONSES
200
The customer was returned successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
404
The customer was not found.
get/customers/{id}
Production API base URI
https://api.emerchantpayvt.com/api/v2/customers/{id}
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/customers/{id}
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
Expand all Collapse all
{
* "identifier": "string",
* "customer_number": "string",
* "first_name": "string",
* "last_name": "string",
* "email": "string",
* "website": "string",
* "phone": "string",
* "alternate_phone": "string",
* "billing_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "shipping_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "active": true,
* "id": 1
}
UPDATE A CUSTOMER
Updates a single customer by ID number
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The customer ID.
REQUEST BODY SCHEMA: APPLICATION/JSON
identifier
string <= 255 characters
Something that identifies the customer, e.g. the customer's name or company.
customer_number
string <= 255 characters
A custom identifier.
first_name
string <= 255 characters
last_name
string <= 255 characters
email
string <= 255 characters
website
string <= 255 characters
phone
string <= 255 characters
alternate_phone
string <= 255 characters
billing_info
object (Address)
shipping_info
object (Address)
active
boolean
Default: true
RESPONSES
200
The customer was updated successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
404
The customer was not found.
patch/customers/{id}
Production API base URI
https://api.emerchantpayvt.com/api/v2/customers/{id}
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/customers/{id}
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
Expand all Collapse all
{
* "identifier": "string",
* "customer_number": "string",
* "first_name": "string",
* "last_name": "string",
* "email": "string",
* "website": "string",
* "phone": "string",
* "alternate_phone": "string",
* "billing_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "shipping_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "active": true
}
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
Expand all Collapse all
{
* "identifier": "string",
* "customer_number": "string",
* "first_name": "string",
* "last_name": "string",
* "email": "string",
* "website": "string",
* "phone": "string",
* "alternate_phone": "string",
* "billing_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "shipping_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "active": true,
* "id": 1
}
DELETE A CUSTOMER
Delete a single customer by customer ID.
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The customer ID.
RESPONSES
204
The customer was deleted successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
404
The customer was not found.
409
The customer is linked to active recurring schedules.
delete/customers/{id}
Production API base URI
https://api.emerchantpayvt.com/api/v2/customers/{id}
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/customers/{id}
GET PAYMENT METHODS FOR A CUSTOMER
Returns the payment methods for the specified customer
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The customer ID.
RESPONSES
200
The payment methods were returned successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
404
The customer was not found.
get/customers/{id}/payment-methods
Production API base URI
https://api.emerchantpayvt.com/api/v2/customers/{id}/payment-methods
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/customers/{id}/payment-methods
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
Expand all Collapse all
[
* {
* "id": 1,
* "customer_id": 1,
* "created_at": "2019-08-24T14:15:22Z",
* "avs_address": "string",
* "avs_zip": "string",
* "name": "string",
* "expiry_month": 1,
* "expiry_year": 2020,
* "payment_method_type": "card",
* "card_type": "Visa",
* "last4": "stri"
}
]
CREATE A PAYMENT METHOD
Creates a payment method for the specified customer.
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The customer ID.
REQUEST BODY SCHEMA: APPLICATION/JSON
One of
Create Credit Card Payment MethodCreate Check Payment MethodCreate Payment
Method From Source
card
required
string [ 14 .. 16 ] characters ^\d+$
Card number
expiry_month
required
integer [ 1 .. 12 ]
expiry_year
required
integer [ 2020 .. 9999 ]
avs_address
string <= 255 characters
Billing address for the card.
avs_zip
string <= 50 characters
Billing zip code for the card.
While not required, this field should be populated for fraud prevention and to
obtain the best rate for E-commerce credit card transactions.
name
string <= 255 characters
The name on the account.
RESPONSES
201
The payment method was created successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
404
The customer was not found.
409
A payment method with these details already exists for this customer.
415
'Content-Type' must be 'application/json'.
post/customers/{id}/payment-methods
Production API base URI
https://api.emerchantpayvt.com/api/v2/customers/{id}/payment-methods
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/customers/{id}/payment-methods
REQUEST SAMPLES
* Payload
Content type
application/json
Example
Create Credit Card Payment MethodCreate Check Payment MethodCreate Payment
Method From SourceCreate Credit Card Payment Method
Copy
{
* "avs_address": "string",
* "avs_zip": "string",
* "name": "string",
* "expiry_month": 1,
* "expiry_year": 2020,
* "card": "stringstringst"
}
RESPONSE SAMPLES
* 201
* 409
Content type
application/json
Example
Credit Card Payment MethodCheck Payment MethodCredit Card Payment Method
Copy
{
* "id": 1,
* "customer_id": 1,
* "created_at": "2019-08-24T14:15:22Z",
* "avs_address": "string",
* "avs_zip": "string",
* "name": "string",
* "expiry_month": 1,
* "expiry_year": 2020,
* "payment_method_type": "card",
* "card_type": "Visa",
* "last4": "stri"
}
GET RECURRING SCHEDULES FOR A CUSTOMER
Returns the recurring schedules for the specified customer
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The customer ID.
RESPONSES
200
The recurring schedules were returned successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
404
The customer was not found.
get/customers/{id}/recurring-schedules
Production API base URI
https://api.emerchantpayvt.com/api/v2/customers/{id}/recurring-schedules
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/customers/{id}/recurring-schedules
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
Expand all Collapse all
[
* {
* "title": "string",
* "frequency": "daily",
* "amount": 0.01,
* "next_run_date": "2019-08-24",
* "num_left": 0,
* "payment_method_id": 1,
* "active": true,
* "receipt_email": "string",
* "status": "active",
* "prev_run_date": "2019-08-24",
* "transaction_count": 0,
* "id": 1,
* "customer_id": 1,
* "created_at": "2019-08-24T14:15:22Z"
}
]
CREATE A RECURRING SCHEDULE
Creates a recurring schedule for the specified customer.
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The customer ID.
REQUEST BODY SCHEMA: APPLICATION/JSON
title
required
string <= 255 characters
amount
required
number [ 0.01 .. 20000000 ]
Amount to bill.
If a mandatory surcharge is set by the ISO/MSP, the actual amount charged could
be different than the amount submitted in this field.
payment_method_id
required
integer >= 1
Payment method ID
frequency
string
Default: "monthly"
Enum: "daily" "weekly" "biweekly" "monthly" "bimonthly" "quarterly" "biannually"
"annually"
next_run_date
string <date>
Next date that the schedule will run. The default is tomorrow in EST.
num_left
integer >= 0
Default: 0
Number of times the schedule has left to bill. Set to 0 for ongoing.
active
boolean
Default: true
receipt_email
string <= 255 characters
An email address to send a customer receipt to each time the schedule runs.
use_this_source_key
boolean
Default: false
By default, recurring transactions use the Recurring source key. Set this field
to true to use the source key that this request authenticated with.
RESPONSES
201
The recurring schedule was created successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
404
The customer was not found.
415
'Content-Type' must be 'application/json'.
post/customers/{id}/recurring-schedules
Production API base URI
https://api.emerchantpayvt.com/api/v2/customers/{id}/recurring-schedules
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/customers/{id}/recurring-schedules
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
{
* "title": "string",
* "frequency": "daily",
* "amount": 0.01,
* "next_run_date": "2019-08-24",
* "num_left": 0,
* "payment_method_id": 1,
* "active": true,
* "receipt_email": "string",
* "use_this_source_key": false
}
RESPONSE SAMPLES
* 201
Content type
application/json
Copy
{
* "title": "string",
* "frequency": "daily",
* "amount": 0.01,
* "next_run_date": "2019-08-24",
* "num_left": 0,
* "payment_method_id": 1,
* "active": true,
* "receipt_email": "string",
* "status": "active",
* "prev_run_date": "2019-08-24",
* "transaction_count": 0,
* "id": 1,
* "customer_id": 1,
* "created_at": "2019-08-24T14:15:22Z"
}
GET TRANSACTIONS FOR A CUSTOMER
Get the transactions for the specified customer.
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The customer ID.
QUERY PARAMETERS
order
string
Default: "asc"
Enum: "asc" "desc"
The sort order.
status
Array of strings
Items Enum: "captured" "pending" "reserve" "originated" "returned" "cancelled"
"queued" "declined" "error" "settled" "voided" "approved" "blocked" "expired"
The transaction status(es) to filter by. Multiple values can be sent, separated
by commas.
payment_type
Array of strings
Items Enum: "credit_card" "check"
The transaction payment type(s) to filter by. Multiple values can be sent,
separated by commas.
settled_date
string <date>
The settled date in UTC to filter for. This will exclude transactions processed
more than 30 days before the specified settlement date, regardless of the
date_from query parameter.
date_field
string
Default: "created_at"
Enum: "settled_at" "created_at"
The date event to filter by. This field only has an effect when combined with
date_from and date_to filters
date_from
integer or string
The earliest date to search. This will be rounded down to the beginning of the
day in UTC.
date_to
integer or string
The latest date to search. This will be rounded up to the end of the day in UTC.
limit
integer [ 1 .. 100 ]
Default: 10
The maximum number of results to return.
offset
integer >= 0
The 0-based offset to start from.
RESPONSES
200
The transactions were retrieved successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
404
The customer was not found.
get/customers/{id}/transactions
Production API base URI
https://api.emerchantpayvt.com/api/v2/customers/{id}/transactions
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/customers/{id}/transactions
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
Expand all Collapse all
[
* {
* "id": 1,
* "created_at": "2019-08-24T14:15:22Z",
* "settled_date": "2019-08-24",
* "amount_details": {
* "amount": 0.01,
* "tax": 0,
* "surcharge": 0,
* "shipping": 0,
* "tip": 0,
* "discount": 0,
* "subtotal": 0,
* "original_requested_amount": 0.01,
* "original_authorized_amount": 0.01
},
* "transaction_details": {
* "description": "string",
* "clerk": "string",
* "terminal": "string",
* "client_ip": "string",
* "signature": "string",
* "invoice_number": "string",
* "po_number": "string",
* "order_number": "string",
* "batch_id": 1,
* "source": "string",
* "username": "string",
* "type": "charge",
* "reference_number": 1
},
* "customer": {
* "identifier": "string",
* "email": "string",
* "fax": "string",
* "customer_id": 1
},
* "status_details": {
* "error_code": "string",
* "error_message": "string",
* "status": "captured"
},
* "billing_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "shipping_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "custom_fields": {
* "custom1": "string",
* "custom2": "string",
* "custom3": "string",
* "custom4": "string",
* "custom5": "string",
* "custom6": "string",
* "custom7": "string",
* "custom8": "string",
* "custom9": "string",
* "custom10": "string",
* "custom11": "string",
* "custom12": "string",
* "custom13": "string",
* "custom14": "string",
* "custom15": "string",
* "custom16": "string",
* "custom17": "string",
* "custom18": "string",
* "custom19": "string",
* "custom20": "string"
},
* "card_details": {
* "name": "string",
* "last4": "stri",
* "expiry_month": 1,
* "expiry_year": 2020,
* "card_type": "Visa",
* "avs_street": "string",
* "avs_zip": "string",
* "auth_code": "string",
* "bin": "string",
* "avs_result": "string",
* "avs_result_code": "YYY",
* "cvv_result": "string",
* "cvv_result_code": "M",
* "cavv_result": "string",
* "cavv_result_code": "string"
}
}
]
PAYMENT METHODS
Payment Methods are stored credit cards or bank account information.
GET ALL PAYMENT METHODS
Returns a paginated list of all payment methods.
AUTHORIZATIONS:
BasicAuthentication
QUERY PARAMETERS
order
string
Default: "asc"
Enum: "asc" "desc"
The sort order.
limit
integer [ 1 .. 100 ]
Default: 10
The maximum number of results to return.
offset
integer >= 0
The 0-based offset to start from.
RESPONSES
200
The payment methods were retrieved successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
get/payment-methods
Production API base URI
https://api.emerchantpayvt.com/api/v2/payment-methods
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/payment-methods
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
Expand all Collapse all
[
* {
* "id": 1,
* "customer_id": 1,
* "created_at": "2019-08-24T14:15:22Z",
* "avs_address": "string",
* "avs_zip": "string",
* "name": "string",
* "expiry_month": 1,
* "expiry_year": 2020,
* "payment_method_type": "card",
* "card_type": "Visa",
* "last4": "stri"
}
]
GET A SINGLE PAYMENT METHOD
Get a single payment method by payment method ID.
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The payment method ID.
RESPONSES
200
The payment method was retrieved successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
404
The payment method was not found.
get/payment-methods/{id}
Production API base URI
https://api.emerchantpayvt.com/api/v2/payment-methods/{id}
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/payment-methods/{id}
RESPONSE SAMPLES
* 200
Content type
application/json
Example
Credit Card Payment MethodCheck Payment MethodCredit Card Payment Method
Copy
{
* "id": 1,
* "customer_id": 1,
* "created_at": "2019-08-24T14:15:22Z",
* "avs_address": "string",
* "avs_zip": "string",
* "name": "string",
* "expiry_month": 1,
* "expiry_year": 2020,
* "payment_method_type": "card",
* "card_type": "Visa",
* "last4": "stri"
}
UPDATE A PAYMENT METHOD
Updates a payment method by ID number
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The payment method ID.
REQUEST BODY SCHEMA: APPLICATION/JSON
One of
Credit Card Payment MethodCheck Payment Method
avs_address
string <= 255 characters
Billing address for the card.
avs_zip
string <= 50 characters
Billing zip code for the card.
While not required, this field should be populated for fraud prevention and to
obtain the best rate for E-commerce credit card transactions.
name
string <= 255 characters
The name on the account.
expiry_month
integer [ 1 .. 12 ]
expiry_year
integer [ 2020 .. 9999 ]
RESPONSES
200
The payment method was updated successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
404
The payment method was not found.
patch/payment-methods/{id}
Production API base URI
https://api.emerchantpayvt.com/api/v2/payment-methods/{id}
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/payment-methods/{id}
REQUEST SAMPLES
* Payload
Content type
application/json
Example
Credit Card Payment MethodCheck Payment MethodCredit Card Payment Method
Copy
{
* "avs_address": "string",
* "avs_zip": "string",
* "name": "string",
* "expiry_month": 1,
* "expiry_year": 2020
}
RESPONSE SAMPLES
* 200
Content type
application/json
Example
Credit Card Payment MethodCheck Payment MethodCredit Card Payment Method
Copy
{
* "id": 1,
* "customer_id": 1,
* "created_at": "2019-08-24T14:15:22Z",
* "avs_address": "string",
* "avs_zip": "string",
* "name": "string",
* "expiry_month": 1,
* "expiry_year": 2020,
* "payment_method_type": "card",
* "card_type": "Visa",
* "last4": "stri"
}
DELETE A PAYMENT METHOD
Delete a single payment method by payment method ID.
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The payment method ID.
RESPONSES
204
The payment method was deleted successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
404
The payment method was not found.
409
The payment method is linked to active recurring schedules.
delete/payment-methods/{id}
Production API base URI
https://api.emerchantpayvt.com/api/v2/payment-methods/{id}
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/payment-methods/{id}
GET RECURRING SCHEDULES FOR A PAYMENT METHOD
Returns the recurring schedules for the specified payment method
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The payment method ID.
RESPONSES
200
The recurring schedules were returned successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
404
The payment method was not found.
get/payment-methods/{id}/recurring-schedules
Production API base URI
https://api.emerchantpayvt.com/api/v2/payment-methods/{id}/recurring-schedules
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/payment-methods/{id}/recurring-schedules
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
{
* "title": "string",
* "frequency": "daily",
* "amount": 0.01,
* "next_run_date": "2019-08-24",
* "num_left": 0,
* "payment_method_id": 1,
* "active": true,
* "receipt_email": "string",
* "status": "active",
* "prev_run_date": "2019-08-24",
* "transaction_count": 0,
* "id": 1,
* "customer_id": 1,
* "created_at": "2019-08-24T14:15:22Z"
}
RECURRING SCHEDULES
GET ALL RECURRING SCHEDULES
Returns a paginated list of all recurring schedules.
AUTHORIZATIONS:
BasicAuthentication
QUERY PARAMETERS
order
string
Default: "asc"
Enum: "asc" "desc"
The sort order.
limit
integer [ 1 .. 100 ]
Default: 10
The maximum number of results to return.
offset
integer >= 0
The 0-based offset to start from.
RESPONSES
200
The recurring schedules were retrieved successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
get/recurring-schedules
Production API base URI
https://api.emerchantpayvt.com/api/v2/recurring-schedules
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/recurring-schedules
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
Expand all Collapse all
[
* {
* "title": "string",
* "frequency": "daily",
* "amount": 0.01,
* "next_run_date": "2019-08-24",
* "num_left": 0,
* "payment_method_id": 1,
* "active": true,
* "receipt_email": "string",
* "status": "active",
* "prev_run_date": "2019-08-24",
* "transaction_count": 0,
* "id": 1,
* "customer_id": 1,
* "created_at": "2019-08-24T14:15:22Z"
}
]
GET A SINGLE RECURRING SCHEDULE
Get a single recurring schedules by ID.
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The recurring schedule ID.
RESPONSES
200
The recurring schedule was retrieved successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
404
The recurring schedule was not found.
get/recurring-schedules/{id}
Production API base URI
https://api.emerchantpayvt.com/api/v2/recurring-schedules/{id}
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/recurring-schedules/{id}
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
{
* "title": "string",
* "frequency": "daily",
* "amount": 0.01,
* "next_run_date": "2019-08-24",
* "num_left": 0,
* "payment_method_id": 1,
* "active": true,
* "receipt_email": "string",
* "status": "active",
* "prev_run_date": "2019-08-24",
* "transaction_count": 0,
* "id": 1,
* "customer_id": 1,
* "created_at": "2019-08-24T14:15:22Z"
}
UPDATE A RECURRING SCHEDULE
Updates a recurring schedule by ID number
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The recurring schedule ID.
REQUEST BODY SCHEMA: APPLICATION/JSON
title
string <= 255 characters
frequency
string
Default: "monthly"
Enum: "daily" "weekly" "biweekly" "monthly" "bimonthly" "quarterly" "biannually"
"annually"
amount
number [ 0.01 .. 20000000 ]
Amount to bill.
If a mandatory surcharge is set by the ISO/MSP, the actual amount charged could
be different than the amount submitted in this field.
next_run_date
string <date>
Next date that the schedule will run. The default is tomorrow in EST.
num_left
integer >= 0
Default: 0
Number of times the schedule has left to bill. Set to 0 for ongoing.
payment_method_id
integer >= 1
Payment method ID
active
boolean
Default: true
receipt_email
string <= 255 characters
An email address to send a customer receipt to each time the schedule runs.
RESPONSES
200
The recurring schedule was updated successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
404
The recurring schedule was not found.
patch/recurring-schedules/{id}
Production API base URI
https://api.emerchantpayvt.com/api/v2/recurring-schedules/{id}
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/recurring-schedules/{id}
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
{
* "title": "string",
* "frequency": "daily",
* "amount": 0.01,
* "next_run_date": "2019-08-24",
* "num_left": 0,
* "payment_method_id": 1,
* "active": true,
* "receipt_email": "string"
}
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
{
* "title": "string",
* "frequency": "daily",
* "amount": 0.01,
* "next_run_date": "2019-08-24",
* "num_left": 0,
* "payment_method_id": 1,
* "active": true,
* "receipt_email": "string",
* "status": "active",
* "prev_run_date": "2019-08-24",
* "transaction_count": 0,
* "id": 1,
* "customer_id": 1,
* "created_at": "2019-08-24T14:15:22Z"
}
DELETE A RECURRING SCHEDULE
Delete a single recurring schedule by ID.
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The recurring schedule ID.
RESPONSES
204
The recurring schedule was deleted successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
404
The recurring schedule was not found.
delete/recurring-schedules/{id}
Production API base URI
https://api.emerchantpayvt.com/api/v2/recurring-schedules/{id}
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/recurring-schedules/{id}
GET TRANSACTIONS FOR A RECURRING SCHEDULE
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The recurring schedule ID.
QUERY PARAMETERS
order
string
Default: "asc"
Enum: "asc" "desc"
The sort order.
status
Array of strings
Items Enum: "captured" "pending" "reserve" "originated" "returned" "cancelled"
"queued" "declined" "error" "settled" "voided" "approved" "blocked" "expired"
The transaction status(es) to filter by. Multiple values can be sent, separated
by commas.
payment_type
Array of strings
Items Enum: "credit_card" "check"
The transaction payment type(s) to filter by. Multiple values can be sent,
separated by commas.
settled_date
string <date>
The settled date in UTC to filter for. This will exclude transactions processed
more than 30 days before the specified settlement date, regardless of the
date_from query parameter.
date_field
string
Default: "created_at"
Enum: "settled_at" "created_at"
The date event to filter by. This field only has an effect when combined with
date_from and date_to filters
date_from
integer or string
The earliest date to search. This will be rounded down to the beginning of the
day in UTC.
date_to
integer or string
The latest date to search. This will be rounded up to the end of the day in UTC.
limit
integer [ 1 .. 100 ]
Default: 10
The maximum number of results to return.
offset
integer >= 0
The 0-based offset to start from.
RESPONSES
200
The transactions were retrieved successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
404
The recurring schedule was not found.
get/recurring-schedules/{id}/transactions
Production API base URI
https://api.emerchantpayvt.com/api/v2/recurring-schedules/{id}/transactions
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/recurring-schedules/{id}/transactions
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
Expand all Collapse all
[
* {
* "id": 1,
* "created_at": "2019-08-24T14:15:22Z",
* "settled_date": "2019-08-24",
* "amount_details": {
* "amount": 0.01,
* "tax": 0,
* "surcharge": 0,
* "shipping": 0,
* "tip": 0,
* "discount": 0,
* "subtotal": 0,
* "original_requested_amount": 0.01,
* "original_authorized_amount": 0.01
},
* "transaction_details": {
* "description": "string",
* "clerk": "string",
* "terminal": "string",
* "client_ip": "string",
* "signature": "string",
* "invoice_number": "string",
* "po_number": "string",
* "order_number": "string",
* "batch_id": 1,
* "source": "string",
* "username": "string",
* "type": "charge",
* "reference_number": 1
},
* "customer": {
* "identifier": "string",
* "email": "string",
* "fax": "string",
* "customer_id": 1
},
* "status_details": {
* "error_code": "string",
* "error_message": "string",
* "status": "captured"
},
* "billing_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "shipping_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "custom_fields": {
* "custom1": "string",
* "custom2": "string",
* "custom3": "string",
* "custom4": "string",
* "custom5": "string",
* "custom6": "string",
* "custom7": "string",
* "custom8": "string",
* "custom9": "string",
* "custom10": "string",
* "custom11": "string",
* "custom12": "string",
* "custom13": "string",
* "custom14": "string",
* "custom15": "string",
* "custom16": "string",
* "custom17": "string",
* "custom18": "string",
* "custom19": "string",
* "custom20": "string"
},
* "card_details": {
* "name": "string",
* "last4": "stri",
* "expiry_month": 1,
* "expiry_year": 2020,
* "card_type": "Visa",
* "avs_street": "string",
* "avs_zip": "string",
* "auth_code": "string",
* "bin": "string",
* "avs_result": "string",
* "avs_result_code": "YYY",
* "cvv_result": "string",
* "cvv_result_code": "M",
* "cavv_result": "string",
* "cavv_result_code": "string"
}
}
]
PRODUCTS
GET PRODUCTS
Returns a list of all products.
AUTHORIZATIONS:
BasicAuthentication
QUERY PARAMETERS
order
string
Default: "asc"
Enum: "asc" "desc"
The sort order.
limit
integer [ 1 .. 100 ]
Default: 10
The maximum number of results to return.
offset
integer >= 0
The 0-based offset to start from.
selected_fields
Array of strings
An array of fields to return. Defaults to all available fields.
filter_fields
Array of strings
An array of fields to search, used together with filter_string. Defaults to all
selected fields.
filter_string
string
The string to search for in all fields specified in filter_fields.
category_id
Array of integers
An array of category ids to filter products by. Defaults to all categories.
RESPONSES
200
Product list was retrieved successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
get/products
Production API base URI
https://api.emerchantpayvt.com/api/v2/products
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/products
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
Expand all Collapse all
[
* {
* "id": 0,
* "quantity_on_order": 0,
* "created_at": "2019-08-24T14:15:22Z",
* "enabled": true,
* "name": "string",
* "manufacturer": "string",
* "model": "string",
* "sku": "string",
* "upc": "string",
* "weight": "string",
* "url": "string",
* "description": "string",
* "price": 0.0001,
* "category_id": 0,
* "enabled_from_date": "2019-08-24",
* "ship_weight": "string",
* "sale_price": 0.0001,
* "quantity_on_hand": 0,
* "min_quantity": 1
}
]
CREATE A NEW PRODUCT
AUTHORIZATIONS:
BasicAuthentication
REQUEST BODY SCHEMA: APPLICATION/JSON
price
required
number [ 0.0001 .. 20000000 ]
The price of the product.
enabled
boolean
Default: true
If the product is currently enabled.
name
string <= 255 characters
The name of the product.
manufacturer
string [ 1 .. 255 ] characters
The name of the manufacturer.
model
string [ 1 .. 255 ] characters
The model name.
sku
string [ 1 .. 255 ] characters
A SKU for the product.
upc
string [ 1 .. 255 ] characters
A UPC for the product.
weight
string [ 1 .. 255 ] characters
The product's weight.
url
string [ 1 .. 255 ] characters
A web url for the product.
description
string [ 1 .. 255 ] characters
The product description.
category_id
integer
The category that this product belongs in.
enabled_from_date
string <date>
The date that this product is available.
ship_weight
string [ 1 .. 255 ] characters
The product's shipping weight.
sale_price
number [ 0.0001 .. 20000000 ]
The sale price of the product.
quantity_on_hand
integer or null
How many of this product still remains in stock. Set to null for unlimited.
min_quantity
integer
Default: 1
Minimum purchase quantity.
RESPONSES
201
Product was created successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
post/products
Production API base URI
https://api.emerchantpayvt.com/api/v2/products
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/products
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
{
* "enabled": true,
* "name": "string",
* "manufacturer": "string",
* "model": "string",
* "sku": "string",
* "upc": "string",
* "weight": "string",
* "url": "string",
* "description": "string",
* "price": 0.0001,
* "category_id": 0,
* "enabled_from_date": "2019-08-24",
* "ship_weight": "string",
* "sale_price": 0.0001,
* "quantity_on_hand": 0,
* "min_quantity": 1
}
RESPONSE SAMPLES
* 201
Content type
application/json
Copy
{
* "id": 0,
* "quantity_on_order": 0,
* "created_at": "2019-08-24T14:15:22Z",
* "enabled": true,
* "name": "string",
* "manufacturer": "string",
* "model": "string",
* "sku": "string",
* "upc": "string",
* "weight": "string",
* "url": "string",
* "description": "string",
* "price": 0.0001,
* "category_id": 0,
* "enabled_from_date": "2019-08-24",
* "ship_weight": "string",
* "sale_price": 0.0001,
* "quantity_on_hand": 0,
* "min_quantity": 1
}
GET A SINGLE PRODUCT
Returns the requested product.
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The product ID.
RESPONSES
200
product was retrieved successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
404
The product was not found.
get/products/{id}
Production API base URI
https://api.emerchantpayvt.com/api/v2/products/{id}
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/products/{id}
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
{
* "id": 0,
* "quantity_on_order": 0,
* "created_at": "2019-08-24T14:15:22Z",
* "enabled": true,
* "name": "string",
* "manufacturer": "string",
* "model": "string",
* "sku": "string",
* "upc": "string",
* "weight": "string",
* "url": "string",
* "description": "string",
* "price": 0.0001,
* "category_id": 0,
* "enabled_from_date": "2019-08-24",
* "ship_weight": "string",
* "sale_price": 0.0001,
* "quantity_on_hand": 0,
* "min_quantity": 1
}
UPDATE A PRODUCT
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The product ID.
REQUEST BODY SCHEMA: APPLICATION/JSON
enabled
boolean
Default: true
If the product is currently enabled.
name
string <= 255 characters
The name of the product.
manufacturer
string [ 1 .. 255 ] characters
The name of the manufacturer.
model
string [ 1 .. 255 ] characters
The model name.
sku
string [ 1 .. 255 ] characters
A SKU for the product.
upc
string [ 1 .. 255 ] characters
A UPC for the product.
weight
string [ 1 .. 255 ] characters
The product's weight.
url
string [ 1 .. 255 ] characters
A web url for the product.
description
string [ 1 .. 255 ] characters
The product description.
price
number [ 0.0001 .. 20000000 ]
The price of the product.
category_id
integer
The category that this product belongs in.
enabled_from_date
string <date>
The date that this product is available.
ship_weight
string [ 1 .. 255 ] characters
The product's shipping weight.
sale_price
number [ 0.0001 .. 20000000 ]
The sale price of the product.
quantity_on_hand
integer or null
How many of this product still remains in stock. Set to null for unlimited.
min_quantity
integer
Default: 1
Minimum purchase quantity.
RESPONSES
200
Product was updated successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
404
The product was not found.
patch/products/{id}
Production API base URI
https://api.emerchantpayvt.com/api/v2/products/{id}
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/products/{id}
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
{
* "enabled": true,
* "name": "string",
* "manufacturer": "string",
* "model": "string",
* "sku": "string",
* "upc": "string",
* "weight": "string",
* "url": "string",
* "description": "string",
* "price": 0.0001,
* "category_id": 0,
* "enabled_from_date": "2019-08-24",
* "ship_weight": "string",
* "sale_price": 0.0001,
* "quantity_on_hand": 0,
* "min_quantity": 1
}
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
{
* "id": 0,
* "quantity_on_order": 0,
* "created_at": "2019-08-24T14:15:22Z",
* "enabled": true,
* "name": "string",
* "manufacturer": "string",
* "model": "string",
* "sku": "string",
* "upc": "string",
* "weight": "string",
* "url": "string",
* "description": "string",
* "price": 0.0001,
* "category_id": 0,
* "enabled_from_date": "2019-08-24",
* "ship_weight": "string",
* "sale_price": 0.0001,
* "quantity_on_hand": 0,
* "min_quantity": 1
}
DELETE A PRODUCT
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The product ID.
RESPONSES
204
Product was deleted successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
404
The product was not found.
409
This product is in use by an invoice, and cannot be deleted.
delete/products/{id}
Production API base URI
https://api.emerchantpayvt.com/api/v2/products/{id}
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/products/{id}
CATEGORIES
GET ALL CATEGORIES
Returns a list of all product categories.
AUTHORIZATIONS:
BasicAuthentication
QUERY PARAMETERS
order
string
Default: "asc"
Enum: "asc" "desc"
The sort order.
limit
integer [ 1 .. 100 ]
Default: 10
The maximum number of results to return.
offset
integer >= 0
The 0-based offset to start from.
parent_id
integer
For subcategories, set this field to the parent category Id.
RESPONSES
200
Category list was retrieved successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
get/products/categories
Production API base URI
https://api.emerchantpayvt.com/api/v2/products/categories
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/products/categories
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
Expand all Collapse all
[
* {
* "id": 0,
* "name": "string",
* "parent_id": null
}
]
CREATE A NEW CATEGORY
AUTHORIZATIONS:
BasicAuthentication
REQUEST BODY SCHEMA: APPLICATION/JSON
name
required
string
The name of the category.
parent_id
integer or null
Default: null
For subcategories, this field is the parent category ID.
RESPONSES
201
Category was created successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
409
A category already exists with the same name.
post/products/categories
Production API base URI
https://api.emerchantpayvt.com/api/v2/products/categories
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/products/categories
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
{
* "name": "string",
* "parent_id": null
}
RESPONSE SAMPLES
* 201
Content type
application/json
Copy
{
* "id": 0,
* "name": "string",
* "parent_id": null
}
GET A SINGLE CATEGORY
Returns the requested category.
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The category ID.
RESPONSES
200
category was retrieved successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
404
The category was not found.
get/products/categories/{id}
Production API base URI
https://api.emerchantpayvt.com/api/v2/products/categories/{id}
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/products/categories/{id}
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
{
* "id": 0,
* "name": "string",
* "parent_id": null
}
UPDATE A CATEGORY
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The category ID.
REQUEST BODY SCHEMA: APPLICATION/JSON
name
string
The name of the category.
parent_id
integer or null
Default: null
For subcategories, this field is the parent category ID.
RESPONSES
200
Category was updated successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
404
The category was not found.
409
A category already exists with the same name.
patch/products/categories/{id}
Production API base URI
https://api.emerchantpayvt.com/api/v2/products/categories/{id}
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/products/categories/{id}
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
{
* "name": "string",
* "parent_id": null
}
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
{
* "id": 0,
* "name": "string",
* "parent_id": null
}
DELETE A CATEGORY
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The category ID.
RESPONSES
204
Category was deleted successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
404
The category was not found.
409
The category contains products, and cannot be deleted.
delete/products/categories/{id}
Production API base URI
https://api.emerchantpayvt.com/api/v2/products/categories/{id}
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/products/categories/{id}
INVOICES
GET ALL INVOICES
Returns a list of invoices.
AUTHORIZATIONS:
BasicAuthentication
QUERY PARAMETERS
order
string
Default: "asc"
Enum: "asc" "desc"
The sort order.
order_by
string
Default: "id"
Enum: "id" "number" "created" "customer" "due" "amount" "status"
The column to order by.
limit
integer [ 1 .. 100 ]
Default: 10
The maximum number of results to return.
offset
integer >= 0
The 0-based offset to start from.
selected_fields
Array of strings
An array of fields to return. Defaults to all available fields.
product_id
integer
A product ID to filter by.
customer_ids
Array of integers
The customer ID(s) to filter by. Multiple values can be sent, separated by
commas.
statuses
Array of strings
Items Enum: "canceled" "paid" "partially paid" "sent" "viewed" "authorized"
"saved"
The invoice status(es) to filter by. Multiple values can be sent, separated by
commas.
amount
number
Filter invoices by amount.
number
string
Filter invoices by invoice number.
due_date
string <date>
Filter invoices by due date.
created_date
string <date>
Filter invoices by created date. (Note: this is not the invoice date).
RESPONSES
200
Invoice list was retrieved successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
403
You do not have permission to access this feature.
get/invoices
Production API base URI
https://api.emerchantpayvt.com/api/v2/invoices
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/invoices
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
Expand all Collapse all
[
* {
* "id": 0,
* "status": "canceled",
* "to_email": "string",
* "sub_total_amount": 0,
* "total_amount": 0,
* "due_amount": 0,
* "paid_amount": 0,
* "tax": 0,
* "created_at": "2019-08-24T14:15:22Z",
* "products": [
* {
* "id": 0,
* "product_id": null,
* "name": "string",
* "description": "string",
* "price": 20000000,
* "quantity": 0,
* "tax": 20000000,
* "surcharge": 0,
* "subtotal": 0
}
],
* "customer_id": null,
* "number": null,
* "customer_company": "string",
* "customer_email": "string",
* "billing_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "shipping_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "date": "2019-08-24",
* "due_date": "2019-08-24",
* "note": "string",
* "discount": {
* "value": 0,
* "type": "percent"
},
* "requirement": {
* "value": 100,
* "type": "percent"
},
* "surcharge": {
* "card": {
* "value": 0,
* "type": "percent"
},
* "ach": {
* "value": 0,
* "type": "percent"
}
},
* "terms": "string",
* "action": "charge"
}
]
CREATE A NEW INVOICE
AUTHORIZATIONS:
BasicAuthentication
REQUEST BODY SCHEMA: APPLICATION/JSON
products
required
Array of objects (NewInvoiceProduct)
A list of products in the invoice.
customer_id
integer or null
Default: null
The customer ID to send the invoice to. Can be NULL if customer is not saved.
number
string or null
Default: null
The invoice number. Can be alphanumeric.
If set to NULL, will increment the highest numeric invoice number.
customer_company
string <= 255 characters
The customer name.
If invoice is linked to a customer and this field is omitted, will populate from
customer.
customer_email
string <= 255 characters
The customer email.
If invoice is linked to a customer and this field is omitted, will populate from
customer.
billing_info
object
The customer billing info.
If invoice is linked to a customer and this field is omitted, will populate from
customer.
shipping_info
object
The customer shipping info.
If invoice is linked to a customer and this field is omitted, will populate from
customer.
date
string <date>
The invoice date.
Defaults to today's date.
due_date
string <date>
The date the invoice is due.
Defaults to 30 days from invoice date.
note
string
A note to attach to the invoice.
discount
object
Optional discount to apply to the invoice pre tax total.
requirement
object
Total amount that is required with first payment. Defaults to full due amount.
surcharge
object
An optional surcharge to be applied to card or ACH payments. This field will be
overwritten if the ISO/MSP sets a mandatory surcharge.
terms
string
Additional terms to attach to the invoice.
action
string
Default: "charge"
Enum: "charge" "authorize"
The action to process the invoice.
send_invoice
boolean
Default: false
Flag to send invoice to immediately send invoice to customer for payment. Set to
false to save a draft.
email_info
object (InvoiceEmailInfo)
An object containing information related to sending a customer invoice.
RESPONSES
200
Invoice was created successfully, but there were other failures with the
request.
201
Invoice was created successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
403
You do not have permission to access this feature.
post/invoices
Production API base URI
https://api.emerchantpayvt.com/api/v2/invoices
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/invoices
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
Expand all Collapse all
{
* "customer_id": null,
* "number": null,
* "customer_company": "string",
* "customer_email": "string",
* "billing_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "shipping_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "date": "2019-08-24",
* "due_date": "2019-08-24",
* "note": "string",
* "discount": {
* "value": 0,
* "type": "percent"
},
* "requirement": {
* "value": 100,
* "type": "percent"
},
* "surcharge": {
* "card": {
* "value": 0,
* "type": "percent"
},
* "ach": {
* "value": 0,
* "type": "percent"
}
},
* "terms": "string",
* "action": "charge",
* "products": [
* {
* "product_id": null,
* "name": "string",
* "description": "string",
* "price": 20000000,
* "quantity": 0,
* "tax": 20000000
}
],
* "send_invoice": false,
* "email_info": {
* "body": "Dear {customer_name},\n\nPlease see the Invoice {invoice_number}
attached.",
* "subject": "Invoice {invoice_number} from {merchant_company}",
* "to": [
* "string"
],
* "sms_number": [
* "string"
],
* "attach_invoice": true
}
}
RESPONSE SAMPLES
* 200
* 201
Content type
application/json
Copy
Expand all Collapse all
{
* "messages": [
* "string"
],
* "invoice_id": 0
}
GET A SINGLE INVOICE
Returns the requested invoice.
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The invoice ID.
RESPONSES
200
Invoice was retrieved successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
403
You do not have permission to access this feature.
404
The invoice was not found.
get/invoices/{id}
Production API base URI
https://api.emerchantpayvt.com/api/v2/invoices/{id}
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/invoices/{id}
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
Expand all Collapse all
{
* "id": 0,
* "status": "canceled",
* "to_email": "string",
* "sub_total_amount": 0,
* "total_amount": 0,
* "due_amount": 0,
* "paid_amount": 0,
* "tax": 0,
* "created_at": "2019-08-24T14:15:22Z",
* "products": [
* {
* "id": 0,
* "product_id": null,
* "name": "string",
* "description": "string",
* "price": 20000000,
* "quantity": 0,
* "tax": 20000000,
* "surcharge": 0,
* "subtotal": 0
}
],
* "customer_id": null,
* "number": null,
* "customer_company": "string",
* "customer_email": "string",
* "billing_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "shipping_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "date": "2019-08-24",
* "due_date": "2019-08-24",
* "note": "string",
* "discount": {
* "value": 0,
* "type": "percent"
},
* "requirement": {
* "value": 100,
* "type": "percent"
},
* "surcharge": {
* "card": {
* "value": 0,
* "type": "percent"
},
* "ach": {
* "value": 0,
* "type": "percent"
}
},
* "terms": "string",
* "action": "charge"
}
UPDATE AN INVOICE
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The invoice ID.
REQUEST BODY SCHEMA: APPLICATION/JSON
customer_id
integer or null
Default: null
The customer ID to send the invoice to. Can be NULL if customer is not saved.
number
string or null
Default: null
The invoice number. Can be alphanumeric.
If set to NULL, will increment the highest numeric invoice number.
customer_company
string <= 255 characters
The customer name.
If invoice is linked to a customer and this field is omitted, will populate from
customer.
customer_email
string <= 255 characters
The customer email.
If invoice is linked to a customer and this field is omitted, will populate from
customer.
billing_info
object
The customer billing info.
If invoice is linked to a customer and this field is omitted, will populate from
customer.
shipping_info
object
The customer shipping info.
If invoice is linked to a customer and this field is omitted, will populate from
customer.
date
string <date>
The invoice date.
Defaults to today's date.
due_date
string <date>
The date the invoice is due.
Defaults to 30 days from invoice date.
note
string
A note to attach to the invoice.
discount
object
Optional discount to apply to the invoice pre tax total.
requirement
object
Total amount that is required with first payment. Defaults to full due amount.
surcharge
object
An optional surcharge to be applied to card or ACH payments. This field will be
overwritten if the ISO/MSP sets a mandatory surcharge.
terms
string
Additional terms to attach to the invoice.
action
string
Default: "charge"
Enum: "charge" "authorize"
The action to process the invoice.
RESPONSES
200
Invoice was updated successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
403
You do not have permission to access this feature.
404
The invoice was not found.
422
The invoice cannot be updated once it has been paid or cancelled.
patch/invoices/{id}
Production API base URI
https://api.emerchantpayvt.com/api/v2/invoices/{id}
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/invoices/{id}
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
Expand all Collapse all
{
* "customer_id": null,
* "number": null,
* "customer_company": "string",
* "customer_email": "string",
* "billing_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "shipping_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "date": "2019-08-24",
* "due_date": "2019-08-24",
* "note": "string",
* "discount": {
* "value": 0,
* "type": "percent"
},
* "requirement": {
* "value": 100,
* "type": "percent"
},
* "surcharge": {
* "card": {
* "value": 0,
* "type": "percent"
},
* "ach": {
* "value": 0,
* "type": "percent"
}
},
* "terms": "string",
* "action": "charge"
}
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
Expand all Collapse all
{
* "id": 0,
* "status": "canceled",
* "to_email": "string",
* "sub_total_amount": 0,
* "total_amount": 0,
* "due_amount": 0,
* "paid_amount": 0,
* "tax": 0,
* "created_at": "2019-08-24T14:15:22Z",
* "products": [
* {
* "id": 0,
* "product_id": null,
* "name": "string",
* "description": "string",
* "price": 20000000,
* "quantity": 0,
* "tax": 20000000,
* "surcharge": 0,
* "subtotal": 0
}
],
* "customer_id": null,
* "number": null,
* "customer_company": "string",
* "customer_email": "string",
* "billing_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "shipping_info": {
* "first_name": "string",
* "last_name": "string",
* "street": "string",
* "street2": "string",
* "state": "string",
* "city": "string",
* "zip": "string",
* "country": "string",
* "phone": "string"
},
* "date": "2019-08-24",
* "due_date": "2019-08-24",
* "note": "string",
* "discount": {
* "value": 0,
* "type": "percent"
},
* "requirement": {
* "value": 100,
* "type": "percent"
},
* "surcharge": {
* "card": {
* "value": 0,
* "type": "percent"
},
* "ach": {
* "value": 0,
* "type": "percent"
}
},
* "terms": "string",
* "action": "charge"
}
DELETE AN INVOICE
An invoice can only be deleted before a payment is made.
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The invoice ID.
RESPONSES
204
Invoice was deleted successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
403
You do not have permission to access this feature.
404
The invoice was not found.
422
The invoice cannot be deleted.
delete/invoices/{id}
Production API base URI
https://api.emerchantpayvt.com/api/v2/invoices/{id}
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/invoices/{id}
SEND AN EXISTING INVOICE
An invoice can only be sent before a payment is made. Once a payment is made,
you must use the Request final payment endpoint.
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The invoice ID.
REQUEST BODY SCHEMA: APPLICATION/JSON
body
string
Default: "Dear {customer_name},\n\nPlease see the Invoice {invoice_number}
attached."
An email body.
The default value will fill in the templated fields. If you supply a body text,
it will be sent exactly as supplied without any parsing. However, you can add
special escape characters such as \n for new-line
subject
string
Default: "Invoice {invoice_number} from {merchant_company}"
The email subject.
The default value will fill in the templated fields. If you supply a subject
text, it will be sent exactly as supplied without any parsing.
to
Array of strings
A list of email addresses to send to. If not supplied, will populate from
customer_email field.
sms_number
Array of strings
A list of numbers to send an sms to.
attach_invoice
boolean
Default: true
Specify if system invoice should be attached to the email.
RESPONSES
204
Invoice was sent successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
403
You do not have permission to access this feature.
404
The invoice was not found.
422
The invoice cannot be sent.
post/invoices/{id}/send
Production API base URI
https://api.emerchantpayvt.com/api/v2/invoices/{id}/send
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/invoices/{id}/send
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
Expand all Collapse all
{
* "body": "Dear {customer_name},\n\nPlease see the Invoice {invoice_number}
attached.",
* "subject": "Invoice {invoice_number} from {merchant_company}",
* "to": [
* "string"
],
* "sms_number": [
* "string"
],
* "attach_invoice": true
}
CANCEL AN EXISTING INVOICE
An invoice can only be canceled once it is sent, but before a payment is made.
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The invoice ID.
RESPONSES
204
Invoice was canceled successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
403
You do not have permission to access this feature.
404
The invoice was not found.
422
The invoice cannot be canceled.
post/invoices/{id}/cancel
Production API base URI
https://api.emerchantpayvt.com/api/v2/invoices/{id}/cancel
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/invoices/{id}/cancel
REACTIVATE A CANCELED INVOICE
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The invoice ID.
REQUEST BODY SCHEMA: APPLICATION/JSON
body
string
Default: "Dear {customer_name},\n\nPlease see the Invoice {invoice_number}
attached."
An email body.
The default value will fill in the templated fields. If you supply a body text,
it will be sent exactly as supplied without any parsing. However, you can add
special escape characters such as \n for new-line
subject
string
Default: "Reactivated Invoice {invoice_number} from {merchant_company}"
The email subject.
The default value will fill in the templated fields. If you supply a subject
text, it will be sent exactly as supplied without any parsing.
to
Array of strings
A list of email addresses to send to. If not supplied, will populate from
customer_email field.
sms_number
Array of strings
A list of numbers to send an sms to.
attach_invoice
boolean
Default: true
Specify if system invoice should be attached to the email.
RESPONSES
204
Invoice was reactivated successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
403
You do not have permission to access this feature.
404
The invoice was not found.
422
The invoice cannot be reactivated because it has not been canceled.
post/invoices/{id}/reactivate
Production API base URI
https://api.emerchantpayvt.com/api/v2/invoices/{id}/reactivate
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/invoices/{id}/reactivate
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
Expand all Collapse all
{
* "body": "Dear {customer_name},\n\nPlease see the Invoice {invoice_number}
attached.",
* "subject": "Reactivated Invoice {invoice_number} from {merchant_company}",
* "to": [
* "string"
],
* "sms_number": [
* "string"
],
* "attach_invoice": true
}
REQUEST FINAL PAYMENT FOR AN INVOICE
Final payment can only be requested for an active invoice that is partially
paid.
AUTHORIZATIONS:
BasicAuthentication
PATH PARAMETERS
id
required
integer >= 1
The invoice ID.
REQUEST BODY SCHEMA: APPLICATION/JSON
body
string
Default: "Dear {customer_name},\n\nPlease see the Invoice {invoice_number}
attached."
An email body.
The default value will fill in the templated fields. If you supply a body text,
it will be sent exactly as supplied without any parsing. However, you can add
special escape characters such as \n for new-line
subject
string
Default: "Invoice {invoice_number} from {merchant_company}"
The email subject.
The default value will fill in the templated fields. If you supply a subject
text, it will be sent exactly as supplied without any parsing.
to
Array of strings
A list of email addresses to send to. If not supplied, will populate from
customer_email field.
sms_number
Array of strings
A list of numbers to send an sms to.
attach_invoice
boolean
Default: true
Specify if system invoice should be attached to the email.
RESPONSES
204
Payment request was sent successfully.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
403
You do not have permission to access this feature.
404
The invoice was not found.
422
The request cannot be sent.
post/invoices/{id}/request-final
Production API base URI
https://api.emerchantpayvt.com/api/v2/invoices/{id}/request-final
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/invoices/{id}/request-final
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
Expand all Collapse all
{
* "body": "Dear {customer_name},\n\nPlease see the Invoice {invoice_number}
attached.",
* "subject": "Invoice {invoice_number} from {merchant_company}",
* "to": [
* "string"
],
* "sms_number": [
* "string"
],
* "attach_invoice": true
}
APPLE PAY SESSION
GET AN APPLE PAY SESSION
Use this endpoint to get an Apple Pay session before processing an Apple Pay
transaction.
The url parameter will be supplied by the Apple Pay JS library when the
onvalidatemerchant handler is invoked.
AUTHORIZATIONS:
BasicAuthentication
REQUEST BODY SCHEMA: APPLICATION/JSON
url
required
string
The URL retrieved from the validationURL property of the data passed to the
client-side onvalidatemerchant event.
RESPONSES
200
Successfully retrieved Apple Session.
400
The request was invalid or missing required fields.
401
Credentials are missing or invalid.
500
There was an error retreiving an Apple Session
post/apple-pay/session
Production API base URI
https://api.emerchantpayvt.com/api/v2/apple-pay/session
Sandbox API base URI
https://api.sandbox.emerchantpayvt.com/api/v2/apple-pay/session
REQUEST SAMPLES
* Payload
Content type
application/json
Copy
{
* "url": "string"
}
RESPONSE SAMPLES
* 200
Content type
application/json
Copy
{ }