Appearance
Requests
Base Urls
Sandbox
The Sandbox environment is provided for testing. Transaction responses are simulated and do not leave the platform for processing. No billing related items occur within this environment.
Sandbox url:
Production
The Production environment should be used for all LIVE transactional processing.
Production url:
Versioning
The platform's semi-RESTful API is fully backwards compatible and versioning is not necessary. Changes and feature updates are sent out via the platform prior to release.
Current version:
1.5.1
Headers
The following headers should be included with your requests:
Authorization
Calls to the API must include an Authorization header with the request. Either a JWT (JSON Web Token) or an API Key can be used as the value of this header, like so:
Authorization: Bearer { JWTToken }
Authorization: { API Key }
Api Keys
API keys are used to authenticate your requests to the API. You can create and manage your API keys in the control panel. API keys are tied to a user account.
Their are two types of API keys:
- Public API keys (ex: pub_***) - used for making requests to the API from the client side (ex. Tokenizer and Cart Sessions)
- Private API keys (ex: api_***) - used for making requests to the API from the server side (ex. Transaction Processing)
DANGER
Private API keys should never be exposed to the public. Please do not include them in client side code, emails or support ticket request.
DANGER
Use of Public API keys to make requests to the API from the server side will result in an unauthorzed response.
Content-Type
Content-Type
should typically be set to application/json
, unless you need to send your request body in a different format. All API responses will be in JSON format.
Transactions
Process
Process a transaction through the gateway.
TIP
If you do not have a default processor set, you must include the processor_id
property in the request body or the transaction will fail.
TIP
Base Amount - If you are using base_amount it will be the base amount of the transaction. The surcharge and other related fees(if applicable) will be calculated and added unless those values are specifically passed in.
Amount - This will be the final amount you want charged and will include all surcharges and related fees(if applicable).
Request Method:
POST
URL Endpoint:
/api/transaction
Name | Type | Default | Description | Required |
---|---|---|---|---|
idempotency_key | uint(uuid format) | used to identify duplicate transactions. Default time is 5 minutes | ||
type | string | "sale", "authorize", "verification" or "credit" | ||
amount | integer | Amount to process in cents (should contain all applicable fees and taxes) (1299 = $12.99) | ||
base_amount | integer | Amount to process in cents (surcharge and related fees will be added to this amount during processing) (1299 = $12.99) | ||
tax_exempt | boolean | false | Is the transaction tax exempt | Required for L3 |
tax_amount | integer | 0 | Tax Amount in cents | Required for L3 |
shipping_amount | integer | 0 | Shipping Amount in cents (should be included in Amount) | |
discount_amount | integer | 0 | Discount Amount in cents (should be included in Amount) | |
tip_amount | integer | 0 | Tip Amount in cents (should be included in Amount) | |
currency | string | "USD" | ISO 4217 currency (ex "USD") | |
description | string | "" | Text field for miscellaneous notes (max 255 characters) | |
order_id | string | Supports up to 15 alphanumeric characters | Required for L3 | |
po_number | string | Supports up to 15 alphanumeric characters | ||
processor_id | string | "" | Designates a specific processor for the transaction. If no value is provided, the transaction will run against the default processor set on your gateway. If no value is provided and there is no default set, the transaction will fail. | see description |
ip_address | string | Server IP | IPv4 or IPv6 value of the end user | |
allow_partial_payment | bool | false | Allow partial transactions to be approved (only if supported by processor) | |
email_receipt | boolean | false | If true, sends an email receipt (email_address must be provided) | |
email_address | string | Email address (must be valid email format, "example@mail.com") | required if email_receipt is true | |
create_vault_record | boolean | false | If true, triggers the creation of a customer vault record after a successful transaction. Multiple transactions with the same details will create duplicative customer records. | |
vendor_id | string | "" | Vendor ID passed along to certain processors if supported (Special Field, only use if instructed by support) | |
billing_method | string | "straight" | "straight", "initial_recurring", or "recurring" | |
summary_commodity_code | string | Summary Commodity Code 4 AlphaNumeric characters | Required for L3 | |
ship_from_postal_code | string | Ship From Postal Code | Required for L3 | |
payment_adjustment | object | Object containing payment adjustment details. (ex. convenience fees, service fees, and surcharges) | ||
payment_adjustment .type | string | "" | "flat" or "percentage" | |
payment_adjustment .value | integer | 0 | Amount of adjustment in cents for "flat" (ex. 199 = $1.99) or 3 decimal places for "percentage" (ex. 1000 = 1.000%) | |
payment_method | object | Object containing payment method details, must contain only one of the following: card, ach, customer, terminal, token, apm | must include one payment method | |
payment_method .card | object | Object containing details for processing a transaction against a debit or credit card | ||
payment_method .card .entry_type | string | Must be "keyed" or "swiped" | ||
payment_method .card .number | string | Card number (digits only) | required if payment_method.card is present | |
payment_method .card .expiration_date | string | Expiration date (format MM/YY) | required if payment_method.card is present | |
payment_method .card .cvc | string | Card Verification Code | required if the applicable rule is set on the gateway | |
payment_method .card .track_1 | string | Decrypted track_1 | ||
payment_method .card .track_2 | string | Decrypted track_2 | ||
payment_method .card .encrypted_track_1 | string | Encrypted Track 1 | ||
payment_method .card .encrypted_track_2 | string | Encrypted Track 2 | ||
payment_method .card .ksn | string | KSN used to encrypt the supplied encrypted tracks | ||
payment_method .card .cardholder_authentication | object | Optionally pass 3DS collected data | if passed, it must contain valid values | |
payment_method .card .cardholder_authentication .eci | string | ECI indicator, ie 01,02,05,07..etc | ||
payment_method .card .cardholder_authentication .cavv | string | CAVV | ||
payment_method .card .cardholder_authentication .xid | string | XID | ||
payment_method .card .cardholder_authentication .cryptogram | string | Cryptogram | ||
payment_method .card .cardholder_authentication .version | string | Version, 1 or 2 | ||
payment_method .card .cardholder_authentication .ds_transaction_id | string | DS Transaction ID | ||
payment_method .card .cardholder_authentication .acs_transaction_id | string | ACS Transaction ID | ||
payment_method .ach | object | Object containing details for processing a transaction via ACH | ||
payment_method .ach .routing_number | string | Routing number for account to be charged | required if payment_method.ach is present | |
payment_method .ach .account_number | string | Account number for account to be charged | required if payment_method.ach is present | |
payment_method .ach .sec_code | string | SEC code for ACH transaction type: "web", "ccd", "ppd", or "tel" | required if payment_method.ach is present | |
payment_method .ach .account_type | string | ACH account type: "checking" or "savings" | required if payment_method.ach is present | |
payment_method .ach .check_number | string | Check number | required if payment_method.ach.sec_code = "tel" | |
payment_method .ach .accountholder_authentication | string | Object containing details for accountholder authentication | if required by processor | |
payment_method .ach .accountholder_authentication .dl_state | string | Driver's License state | required if payment_method.ach.accountholder_authentication is present | |
payment_method .ach .accountholder_authentication .dl_number | string | Driver's License number | required if payment_method.ach.accountholder_authentication is present | |
payment_method .customer | object | Object containing details for processing a transaction against a vaulted customer record | ||
payment_method .customer .id | string | Customer ID | required if payment_method.customer is present | |
payment_method .customer .payment_method_id | string | Customer default | ID of customer's saved payment method to be charged | |
payment_method .customer .payment_method_type | string | Customer default | The type of the payment method referenced in payment_method_id | |
payment_method .customer .billing_address_id | string | Customer default | ID of customer's saved billing address to be used | |
payment_method .customer .shipping_address_id | string | Customer default | ID of customer's saved shipping address to be used | |
payment_method .terminal | object | Object containing details for processing a transaction against a Terminal | ||
payment_method .terminal .id | string | ID of the terminal to be used for the transaction | required if payment_method.terminal is present | |
payment_method .terminal .expiration_date | string | Optionally pass an expiration date along with the transaction | ||
payment_method .terminal .cvc | string | Optionally pass a CVV along with the transaction | ||
payment_method .terminal .print_receipt | string | "no" (no receipt), "customer" (customer copy only), "merchant" (merchant copy only), or "both" (both copies) | required if payment_method.terminal is present | |
payment_method .terminal .signature_required | string | If true, requests that the terminal capture a signature (if supported) | required if payment_method.terminal is present | |
payment_method .apm | object | Object containing details for processing APM transactions | ||
payment_method .apm .type | string | APM type (see chart below) | required if payment_method.apm is present | |
payment_method .apm .merchant_redirect_url | string | This is the redirect url you wish to send the customer to after processing the payment | required if payment_method.apm is present | |
payment_method .apm .locale | string | Locale to be used for the payment page, if supported by the APM (ex. "en-US") | required if payment_method.apm is present | |
payment_method .apm .mobile_view | boolean | If true, tells the APM to render a mobile version of the landing page (if supported by the APM) | required if payment_method.apm is present | |
payment_method .apm .national_id | string | Consumer's National ID (max 30 characters) | ||
payment_method .apm .consumer_ref | string | Unique reference identifiying the customer. May contain [a-z0-9-], max 20 characters | ||
billing_address | object | null | Object containing billing address details | |
billing_address .first_name | string | Up to 50 characters | ||
billing_address .last_name | string | Up to 50 characters | ||
billing_address .company | string | Up to 100 characters | ||
billing_address .address_line_1 | string | Up to 100 characters | ||
billing_address .address_line_2 | string | Up to 100 characters | ||
billing_address .city | string | Up to 50 characters | ||
billing_address .state | string | State abbrevation | ||
billing_address .postal_code | string | If payment_method.card is present, defaults to Postal Code associated with card | Required for L3 | |
billing_address .country | string | "US" | ||
billing_address | string | Email address (must be valid email format, "example@mail.com") | ||
billing_address .phone | string | Digits only | ||
billing_address .fax | string | Digits only | ||
shipping_address | object | null | Object containing billing address details | |
shipping_address .first_name | string | Up to 50 characters | ||
shipping_address .last_name | string | Up to 50 characters | ||
shipping_address .company | string | Up to 100 characters | ||
shipping_address .address_line_1 | string | Up to 100 characters | ||
shipping_address .address_line_2 | string | Up to 100 characters | ||
shipping_address .city | string | Up to 50 characters | ||
shipping_address .state | string | State abbreviation | ||
shipping_address .postal_code | string | Required for L3 | ||
shipping_address .country | string | |||
shipping_address | string | Email address (must be valid email format, "example@mail.com") | ||
shipping_address .phone | string | Digits only | ||
shipping_address .fax | string | Digits only | ||
group_name | string | "default" | custom fields group name | |
custom_fields | object | Object based where the key is the id of the custom field and the value is an array of strings(even is single value) | Only required if fields are set to required | |
iias_status | string | "" | Required for HSA/FSA Valid values are: "verified" or "exempt" | |
additional_amounts | object | |||
additional_amounts .hsa .total | int | 0 | Required for HSA/FSA Total amount for HSA/FSA, passed as an unsigned integer | |
additional_amounts .hsa .rx_amount | int | 0 | RX AMount for HSA/FSA, passed as an unsigned integer | |
additional_amounts .hsa .vision_amount | int | 0 | Vision Mount for HSA/FSA, passed as an unsigned integer | |
additional_amounts .hsa .clinic_amount | int | 0 | Clinic Mount for HSA/FSA, passed as an unsigned integer | |
additional_amounts .hsa .dental_amount | int | 0 | Dental Mount for HSA/FSA, passed as an unsigned integer | |
line_items | array | Array of line items | Required for L3 | |
line_items[] name | string | Friendly name up to 50 alpha characters | ||
line_items[] description | string | Product Description up to 50 alpha characters | ||
line_items[] product_code | string | Product Code/SKU up to 50 alpha characters | ||
line_items[] commodity_code | string | Commodity Code up to 12 alpha characters | ||
line_items[] quantity | float64 | Quantity ##.## | ||
line_items[] discount_amount | int | in cents | ||
line_items[] freight_amount | int | in cents | ||
line_items[] unit_price | int | in cents | ||
line_items[] tax_amount | int | in cents | ||
line_items[] national_tax_amount | int | in cents | ||
line_items[] amount | int | in cents | ||
line_items[] national_tax_rate | string | 3 decimal rate. 10% = 10.000 | ||
line_items[] tax_rate | string | 3 decimal rate. 10% = 10.000 | ||
line_items[] unit_of_measure | string | |||
processor_specific | object | Optional: this only applys to specific processor types | ||
processor_specific .paysafe_direct .subscription_trial_solution | bool | |||
processor_specific .paysafe_direct .subscription_start_date | string | YYYY-MM-DD | ||
processor_specific .paysafe_direct .subscription_trial_start_date | string | YYYY-MM-DD | ||
processor_specific .paysafe_direct .subscription_trial_end_date | string | YYYY-MM-DD | ||
processor_specific .paysafe_direct .subscription_secondary_billing_date | string | YYYY-MM-DD | ||
processor_specific .paysafe_direct .subscription_cancel_url | string | weburl | ||
processor_specific .paysafe_direct .subscription_amount | uint | in cents | ||
processor_specific .paysafe_direct .subscription_unit_cost | uint | in cents | ||
processor_specific .paysafe_direct .subscription_item_quantity | uint | |||
processor_specific .paysafe_direct .subscription_product_desc | string | |||
descriptor | object | Optional: this only applys to specific processor types | ||
descriptor .name | string (38 Char) | |||
descriptor .address | string (38 Char) | |||
descriptor .city | string (21 Char) | |||
descriptor .state | string (2 Char) | |||
descriptor .postal_code | string (5 Char) | |||
subscriptions | array | Array of subscriptions | ||
card_on_file_indicator | string | [CR] | Optional value, C = General purpose storage, R = recurring payment | |
initiated_by | string | "customer" or "merchant" | Who is inititating the transaction, "customer" or "merchant" | |
initial_transaction_id | string | Optional if using our tokenization, otherwise this is transaction id used when storing the payment | ||
stored_credential_indicator | string | Optional if using our tokenization, otherwise "used" or "stored" |
Code Samples
bash
curl -v -X POST \
-H "Authorization: APIKEY" \
-H "Content-Type: application/json" \
-d '{
"type": "sale",
"amount": 1112,
"tax_amount": 100,
"shipping_amount": 100,
"currency": "USD",
"description": "test transaction",
"order_id": "someOrderID",
"po_number": "somePONumber",
"ip_address": "4.2.2.2",
"email_receipt": false,
"email_address": "user@home.com",
"create_vault_record": true,
"payment_method": {
"card": {
"entry_type": "keyed",
"number": "4012000098765439",
"expiration_date": "12/20",
"cvc": "999"
}
... or ...
"customer": {
"id": "b798ls2q9qq646ksu070",
"payment_method_type": "card",
"payment_method_id": "b798ls2q9qq646ksu080",
"billing_address_id": "b798ls2q9qq646ksu07g",
"shipping_address_id": "b798ls2q9qq646ksu07g"
}
... or ...
"terminal": {
"id": "<terminal id>"
"expiration_date": "12/20",
"cvc": "999",
"print_receipt": "both"
"signature_required": true
}
... or ...
"token": "<tokenizer token goes here>",
... or ...
"ach": {
"routing_number": "490000018",
"account_number": "999999",
"sec_code": "ccd",
"account_type": "checking",
"check_number":"1223",
"accountholder_authentication": {
"dl_state": "IL",
"dl_number": "r500123123"
}
... or ...
"apm": {
"type": "alipay",
"merchant_redirect_url": "http://merchantwebsite.com/",
"locale": "en-US",
"mobile_view": false
}
}
},
"billing_address" : {
"first_name": "John",
"last_name": "Smith",
"company": "Test Company",
"address_line_1": "123 Some St",
"city": "Wheaton",
"state": "IL",
"postal_code": "60187",
"country": "US",
"phone": "5555555555",
"fax": "5555555555",
"email": "help@website.com"
},
"shipping_address" : {
"first_name": "John",
"last_name": "Smith",
"company": "Test Company",
"address_line_1": "123 Some St",
"city": "Wheaton",
"state": "IL",
"postal_code": "60187",
"country": "US",
"phone": "5555555555",
"fax": "5555555555",
"email": "help@website.com"
}
}' \
"https://sandbox.pepperpaygateway.com/api/transaction"
CIT - MIT
TIP
When processing transactions the following variables are available for including CIT/MIT variables to the processors.
Name | Required | Description |
---|---|---|
card_on_file_indicator | Optional | |
initiated_by | Required | Indicates who initiated the transaction. |
initial_transaction_id | Optional | Optional if using our tokenization |
stored_credential_indicator | Optional | Indicates if a stored payment was used or not |
billing_method | Optional | Defaults to "straight", but if this is a recurring transaction, passing "recurring" will set recurring indicators on the transaction |
Fee Calculation
TIP
Using this endpoint will calculate any applicable fees that should be applied to the transaction. This includes Surcharge, Cash Discount Fees and Payment Adjustment, if applicable.
Request Method:
POST
URL Endpoint:
/api/lookup/fees
Name | Type | Required | Description |
---|---|---|---|
type | string | yes | type of request, "integrations" |
state | string | no | billing address state |
bin | string | yes | 6 - 19 digits of a card |
payment_method | string | yes | card |
base_amount | uint | yes | amount in lowest form of currency. $1.00 = 100 |
json
➜ ~ curl -H 'Authorization: API_KEY' -H "Content-Type: application/json" -X POST -d '{
"type": "integrations",
"type_id":"",
"state": "IL",
"bin": "517246700",
"payment_method": "card",
"base_amount": 1000
}' { url goes here }/api/api/lookup/fees
{
"status": "success",
"msg": "success",
"data": {
"service_fee": 0,
"payment_adjustment": {
"value": 0,
"type": ""
},
"requested_amount": 1350,
"discount_amount": null,
"surcharge": 350
}
}
Amount calculation
Request Method:
POST
URL Endpoint:
/api/calculate/amounts
Name | Type | Required | Default | Description |
---|---|---|---|---|
processor_id | string | true | ||
subtotal | uint | true | null | |
amount | uint | if line_items or products not present | null | |
currency | string | true | ||
payment_method | string | true | Can be 'card' or 'ach' | |
transaction_type | string | true | Can be 'verification', 'auth', 'sale', 'void', 'refund', 'credit' | |
products | array | if amount or line_items not present | null | |
products[].id | string | true | ||
products[].name | string | true | ||
products[].description | string | false | ||
products[].price | string | true | ||
products[].local_tax | string | false | ||
products[].national_tax | string | false | ||
products[].fixed_amount | bool | false | false | |
products[].fixed_qty | bool | false | false | |
products[].unit_of_measure | string | false | null | |
line_items | array | if amount or products not present | null | |
line_items[].id | string | true | ||
line_items[].status | string | true | Can be 'paid', 'pending', 'rejected' | |
line_items[].type | string | true | Can be 'flat' or 'percentage' | |
line_items[].name | string | true | If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000) | |
line_items[].description | string | false | false | If true, the calculated amount will be added to the total amount |
line_items[].unit_price | int | true | ||
line_items[].quantity | float64 | true | ||
line_items[].quantity_shipped | float64 | false | ||
line_items[].product_code | string | false | ||
line_items[].commodity_code | string | false | ||
line_items[].unit_of_measure | string | false | ||
line_items[].alternate_tax_identifier | string | false | ||
line_items[].taxable | bool | false | false | |
line_items[].local_tax_rate | string | false | Format is 10.25 | |
line_items[].national_tax_rate | string | false | Format is 10.25 | |
line_items[].tax_rate | string | false | Format is 10.25 | |
line_items[].discount_amount | uint | false | ||
line_items[].freight_amount | uint | false | ||
line_items[].discount_rate | string | false | ||
processor_payment_adjustment | object | false | null | |
processor_payment_adjustment.type | string | true | Can be 'flat' or 'percentage' | |
processor_payment_adjustment.value | uint | true | If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000) | |
processor_payment_adjustment.include | bool | false | false | If true, the calculated amount will be added to the total amount |
shipping_amount | object | false | null | |
shipping_amount.type | string | true | Can be 'flat' or 'percentage' | |
shipping_amount.value | uint | true | If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000) | |
shipping_amount.include | bool | false | false | If true, the calculated amount will be added to the total amount |
addon_amount | array | false | null | |
addon_amount[].type | string | true | Can be 'flat' or 'percentage' | |
addon_amount[].value | uint | true | If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000) | |
addon_amount[].include | bool | false | false | If true, the calculated amount will be added to the total amount |
discount_amount | array | false | null | |
discount_amount[].type | string | true | Can be 'flat' or 'percentage' | |
discount_amount[].value | uint | true | If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000) | |
discount_amount[].include | bool | false | false | If true, the calculated amount will be added to the total amount |
duty_amount | object | false | null | |
duty_amount.type | string | true | Can be 'flat' or 'percentage' | |
duty_amount.value | uint | true | If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000) | |
duty_amount.include | bool | false | false | If true, the calculated amount will be added to the total amount |
tip_amount | object | false | null | |
tip_amount.type | string | true | Can be 'flat' or 'percentage' | |
tip_amount.value | uint | true | If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000) | |
tip_amount.include | bool | false | false | If true, the calculated amount will be added to the total amount |
additional_amounts | array | false | null | |
additional_amounts[].type | string | true | Can be 'flat' or 'percentage' | |
additional_amounts[].value | uint | true | If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000) | |
additional_amounts[].include | bool | false | false | If true, the calculated amount will be added to the total amount |
tax_amount | object | false | null | |
tax_amount.type | string | true | Can be 'flat' or 'percentage' | |
tax_amount.value | uint | true | If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000) | |
tax_amount.include | bool | false | false | If true, the calculated amount will be added to the total amount |
national_tax_amount | object | false | null | |
national_tax_amount.type | string | true | Can be 'flat' or 'percentage' | |
national_tax_amount.value | uint | true | If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000) | |
national_tax_amount.include | bool | false | false | If true, the calculated amount will be added to the total amount |
local_tax_amount | object | false | null | |
local_tax_amount.type | string | true | Can be 'flat' or 'percentage' | |
local_tax_amount.value | uint | true | If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000) | |
local_tax_amount.include | bool | false | false | If true, the calculated amount will be added to the total amount |
service_fee | object | false | null | |
service_fee.type | string | true | Can be 'flat' or 'percentage' | |
service_fee.value | uint | true | If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000) | |
service_fee.include | bool | false | false | If true, the calculated amount will be added to the total amount |
surcharge | object | false | null | |
surcharge.type | string | true | Can be 'flat' or 'percentage' | |
surcharge.value | uint | true | If type is 'flat', round to 2 decimals (ex. $10.00 should be 1000), if 'percentage' round to 3 (ex. %10.000 should be 10000) | |
surcharge.include | bool | false | false | If true, the calculated amount will be added to the total amount |
cc_bin | string | if surcharge allowed | null | |
country | string | if surcharge allowed | null | |
state | string | if surcharge allowed | null | |
flags | object | false | ||
flags.skip_cash_discount | bool | false | false | If true, skips the cash discount calculation |
flags.skip_surcharge | bool | false | false | If true, skips the cash surcharge calculation |
flags.skip_service_fee | bool | false | false | If true, skips the cash service fee calculation |
flags.skip_consumer_choice | bool | false | false | If true, skips the cash consumer choice calculation |
flags.include_default_tax_to_total | bool | false | null | If true, and tax has not been overridden, the merchant's default tax amount will be added to the total amount |
flags.tax_exempt | bool | false | null | If true, sets the national, local and tax amount fields to 0 |
flags.processor_surcharge_fallback | bool | false | false | If true, processor's surcharge fallback will be available |
flags.add_tax_to_total | bool | false | null | If true, the tax will be added to the total amount |
source | string | false |
Workflow:
- Call the Amount calculation endpoint with the properly filled request
- Take the response of the Amount calculation and place it into the Transaction Request into the
amounts
field and fill the other fields of the request - Submit the transaction with the pre-calculated amounts
sh
➜ ~ curl -H 'Authorization: API_KEY' -H "Content-Type: application/json" -X POST -d '{
"processor_id": "<processor id>",
"amount" : 1000,
"subtotal" : 1000,
"currency": "USD",
"payment_method": "card",
"transaction_type": "sale"
}' { url goes here }/api/calculate/amounts
{
"status": "success",
"msg": "success",
"data": {
"line_items": null,
"shipping_amount": null,
"discount_amount": null,
"freight_amount": null,
"addon_amount": null,
"duty_amount": null,
"tip_amount": null,
"additional_amounts": null,
"tax_amount": 180,
"national_tax_amount": null,
"local_tax_amount": null,
"service_fee": 350,
"surcharge": null,
"processor_id": "<processor id>",
"payment_method": "card",
"included_amounts": {
"shipping_amount": null,
"discount_amount": null,
"duty_amount": null,
"tip_amount": null,
"tax_amount": 180,
"national_tax_amount": null,
"local_tax_amount": null,
"service_fee": 350,
"surcharge": null
},
"subtotal": 1000,
"amount": 1000,
"additional_total": 0,
"total": 1530,
"features": {
"surcharge": false,
"cash_discount": false,
"dual_pricing": false,
"dual_pricing_v2": false
},
"display": {
"subtotal": {
"value": 1000,
"display": true
},
"amount": {
"value": 1000,
"display": true
},
"shipping": {
"value": 0,
"display": false
},
"freight": {
"value": 0,
"display": false
},
"duty": {
"value": 0,
"display": false
},
"discount": {
"value": 0,
"display": false
},
"service_fee": {
"value": 350,
"display": true
},
"surcharge": {
"value": 0,
"display": false
},
"tax": {
"value": 180,
"display": true
},
"national_tax": {
"value": 0,
"display": false
},
"local_tax": {
"value": 0,
"display": false
},
"tip": {
"value": 0,
"display": false
},
"total": {
"value": 1530,
"display": true
},
"consumer_choice": {
"card": 0,
"ach": 0,
"display": false
}
},
"disclaimer": {
"text": "",
"html": "",
"display": false
}
}
}
Response Codes
TIP
Response Codes are grouped as follows: 100 thru 199 are Approvals and Partial Approvals. 200 thru 299 are Declined via the processor. 300 thru 399 are Gateway Declines. 400 thru 499 are processor rejection errors.
Response Code | Processor Definition | Description |
---|---|---|
0 | Unknown | Unknown, please contact support for more information |
99 | Pending payment | Used in redirect processors prior to payment being received |
100 | Approved | Transaction was successfully approved |
110 | Partial approval | Transaction was successfully approved, but for a lesser amount |
200 - 299 | Decline | Transaction has been declined by the issuer for various reasons |
300 - 399 | Gateway Decline | Platform decline for configuration or fraud reasons |
400 - 499 | Transaction error returned by processor | Errors returned from the processor |
AVS Response Codes
Address verification response codes (AVS)
AVS Response Code | Definition | Code Applies to | Card Brands |
---|---|---|---|
0 | AVS Not Available | Domestic + International | V, MC, AX, D, PP, JCB |
A | Address match only | Domestic + International | V, AX, D,PP, JCB |
B | Address matches, ZIP not verified | Domestic + International | V |
C | Incompatible format | Domestic + International | V |
D | Exact match | International | V |
F | Exact match, UK-issued cards | Domestic + International | V |
G | Non-U.S. Issuer does not participate | International | V |
I | Not verified | International | V, D, PP, JCB |
M | Exact match | International | V |
N | No address or ZIP match | Domestic + International | V, MC, AX, D, PP, JCB |
P | Postal Code match | Domestic + International | V |
R | Issuer system unavailable | Domestic | V, MC, AX, D, PP, JCB |
S | Service not supported | Domestic | MC, AX, D, PP, JCB |
U | Address unavailable | Domestic | V, MC, AX, D, PP, JCB |
W | 9-character numeric ZIP match only | Domestic + International (MC) | MC, D, PP, JCB |
X | Exact match, 9-character numeric ZIP | Domestic + International (MC) | MC, D, PP, JCB |
Y | Exact match, 5-character numeric ZIP | Domestic | V, MC, AX, D, PP, JCB |
Z | 5-character ZIP match only | Domestic + International (V) | V, MC, AX, D, PP, JCB |
L | Partial match, Name and billing postal code match | For AMEX cards only | AX |
1 | Cardholder name and ZIP match | Domestic | AX |
2 | Cardholder name, address and ZIP match | Domestic | AX |
3 | Cardholder name and address match | Domestic | AX |
4 | Cardholder name matches | Domestic | AX |
5 | Cardholder name incorrect, ZIP matches | Domestic | AX |
6 | Cardholder name incorrect, address and zip match | Domestic | AX |
7 | Cardholder name incorrect, address matches | Domestic | AX |
8 | Cardholder name, address, and ZIP do not match | Domestic | AX |
Get Transaction By ID
Retrieve details for a specific transaction.
Request Method:
GET
URL Endpoint:
/api/transaction/{ transaction ID }
json
{
"status": "success",
"msg": "success",
"data": [
{
"id": "b7kgflt1tlv51er0fts0",
"type": "sale",
"amount": 1112,
"tax_amount": 100,
"tax_exempt": false,
"shipping_amount": 100,
"currency": "usd",
"description": "test transaction",
"order_id": "someOrderID",
"po_number": "somePONumber",
"ip_address": "4.2.2.2",
"email_receipt": false,
"payment_method": "card",
"response": {
"card": {
"id": "b7kgflt1tlv51er0ftsg",
"card_type": "visa",
"first_six": "401200",
"last_four": "5439",
"masked_card": "401200******5439",
"expiration_date": "12/20",
"status": "approved",
"auth_code": "TAS731",
"processor_response_code": "00",
"processor_response_text": "APPROVAL TAS731 ",
"processor_type": "tsys_sierra",
"processor_id": "b7kgflt1tlv51er0f1sg",
"avs_response_code": "0",
"cvv_response_code": "M",
"processor_specific": {},
"created_at": "2017-10-19T20:15:19.80368Z",
"updated_at": "2017-10-19T20:15:20.777011Z"
}
},
"status": "pending_settlement",
"billing_address": {
"first_name": "John",
"last_name": "Smith",
"company": "Test Company",
"address_line_1": "123 Some St",
"address_line_2": "",
"city": "Wheaton",
"state": "IL",
"postal_code": "60187",
"country": "US",
"phone": "5555555555",
"fax": "5555555555",
"email": "help@website.com"
},
"shipping_address": {
"first_name": "John",
"last_name": "Smith",
"company": "Test Company",
"address_line_1": "123 Some St",
"address_line_2": "",
"city": "Wheaton",
"state": "IL",
"postal_code": "60187",
"country": "US",
"phone": "5555555555",
"fax": "5555555555",
"email": "help@website.com"
},
"created_at": "2017-10-19T20:15:19.560708Z",
"updated_at": "2017-10-19T20:15:20.832049Z"
}
],
"total_count": 1
}
Search Transactions
Retrieve details for all transactions that match provided search criteria.
Request Method:
POST
URL Endpoint:
/api/transaction/search
Name | Type | Description |
---|---|---|
transaction_id | QuerySearchString | Searches for transaction id |
user_id | QuerySearchString | Searches for user_id |
type | QuerySearchString | Searches for transaction type (sale, authorize...etc) |
ip_address | QuerySearchString | Searches for ip_address, either ipv4 or ipv6 |
amount | QuerySearchInt | Searches for originally requested amount |
amount_authorized | QuerySearchInt | Searches for amount_authorized |
amount_captured | QuerySearchInt | Searches for amount_captured |
amount_settled | QuerySearchInt | Searches for amount_settled |
tax_amount | QuerySearchInt | Searches for tax_amount |
po_number | QuerySearchString | Searches for po_number |
order_id | QuerySearchString | Searches for order_id |
payment_method | QuerySearchString | Searches by payment_method, (token, card, terminal) |
payment_type | QuerySearchString | Searches by payment_type (card, echeck) |
status | QuerySearchString | Searches by transaction status (unknown, declined, authorized, pending_settlement, settled, voided, reversed, refunded) |
processor_id | QuerySearchString | Searches by processor_id |
customer_id | QuerySearchString | Searches by customer_id |
created_at | QueryDateRange | Searches by created_at between the provided start_date and end_date. (Dates in UTC "YYYY-MM-DDTHH:II:SSZ") |
captured_at | QueryDateRange | Searches by captured_at between the provided start_date and end_date. (Dates in UTC "YYYY-MM-DDTHH:II:SSZ") |
settled_at | QueryDateRange | Searches by settled_at between the provided start_date and end_date. (Dates in UTC "YYYY-MM-DDTHH:II:SSZ") |
billing_address .address_id | QuerySearchString | Searches by billing_address.id |
billing_address .first_name | QuerySearchString | Searches by billing_address.first_name (0-50 characters) |
billing_address .last_name | QuerySearchString | Searches by billing_address.last_name (0-50 characters) |
billing_address .company | QuerySearchString | Searches by billing_address.company (0-50 characters) |
billing_address .address_line_1 | QuerySearchString | Searches by billing_address.address_line_1 (0-100 characters) |
billing_address .address_line_2 | QuerySearchString | Searches by billing_address.address_line_2 (0-100 characters) |
billing_address .city | QuerySearchString | Searches by billing_address.city (0-50 characters) |
billing_address .state | QuerySearchString | Searches by billing_address.state (2 Character) |
billing_address .postal_code | QuerySearchString | Searches by billing_address.postal_code (0-6 Characters) |
billing_address .country | QuerySearchString | Searches by billing_address.country (2 Characters) |
billing_address | QuerySearchString | Searches by billing_address.email |
billing_address .phone | QuerySearchString | Searches by billing_address.phone (0-14 digits only) |
billing_address .fax | QuerySearchString | Searches by billing_address.fax (0-14 digits only) |
shipping_address .address_id | QuerySearchString | Searches by shipping_address.id |
shipping_address .first_name | QuerySearchString | Searches by shipping_address.first_name (0-50 characters) |
shipping_address .last_name | QuerySearchString | Searches by shipping_address.last_name (0-50 characters) |
shipping_address .company | QuerySearchString | Searches by shipping_address.company (0-50 characters) |
shipping_address .address_line_1 | QuerySearchString | Searches by shipping_address.address_line_1 (0-100 characters) |
shipping_address .address_line_2 | QuerySearchString | Searches by shipping_address.address_line_2 (0-100 characters) |
shipping_address .city | QuerySearchString | Searches by shipping_address.city (0-50 characters) |
shipping_address .state | QuerySearchString | Searches by shipping_address.state (2 Character) |
shipping_address .postal_code | QuerySearchString | Searches by shipping_address.postal_code (0-6 Characters) |
shipping_address .country | QuerySearchString | Searches by shipping_address.country (2 Characters) |
shipping_address | QuerySearchString | Searches by shipping_address.email |
shipping_address .phone | QuerySearchString | Searches by shipping_address.phone (0-14 digits only) |
shipping_address .fax | QuerySearchString | Searches by shipping_address.fax (0-14 digits only) |
limit | integer | Maximum records to return (0-100) |
offset | integer | Number of records to offset the return by |
Request Body Type Values
Type | Operators |
---|---|
QuerySearchString | =, != |
QuerySearchInt | =, !=, <, > |
Capture
Capture funds for a specified transaction that has already been authorized.
Request Method:
POST
URL Endpoint:
/api/transaction/{ transaction ID }/capture
Name | Type | Default | Description | Required |
---|---|---|---|---|
amount | integer | amount from auth | Total amount to capture, in cents. (1299 = $12.99) | |
tax_amount | integer | tax_amount from auth | Tax amount to capture, in cents. (199 = $1.99) | |
shipping_amount | integer | shipping_amount from auth | Shipping amount to capture, in cents. (299 = $2.99) | |
tax_exempt | boolean | false | Is the transaction tax exempt | |
order_id | string | order_id from auth | Alphanumeric (max 17 characters) | |
po_number | string | po_number from auth | Alphanumeric (max 17 characters) | |
ip_address | string | ip_address from auth | IPV4 or IPV6 address |
Void / Auth Reversal
Void a transaction that is pending settlement. Where applicable, a void will be processed as an auth reversal.
Request Method:
POST
URL Endpoint:
/api/transaction/{ transaction ID }/void
json
{
"status": "success",
"msg": "success",
"data": null
}
Refund
Process a refund for a transaction that has already been settled. Multiple partial refunds can be processed, but the total amount of all refunds cannot exceed the previously settled amount.
Request Method:
POST
URL Endpoint:
/api/transaction/{ transaction ID }/refund
Name | Type | Default | Description | Required |
---|---|---|---|---|
amount | integer | amount from auth | Total amount to capture, in cents. (1299 = $12.99) | |
surcharge | integer | null | Surcharge amount, in cents. (1299 = $12.99) |
Settlement Batches
Batch Terminal
You can settle individual terminals by sending a POST
request to the following endpoint: /api/terminal/{terminalID}/settle
Search
Retrieve details for all settlement batches that match provided search criteria.
Request Method:
POST
URL Endpoint:
/api/settlement/batch/search
Name | Type | Default | Description | Required |
---|---|---|---|---|
batch_date | object | Object containing details defining a batch date range | ||
batch_date .start_date | string | "" | Searches by batch_date between the provided start_date and end_date. (Dates in UTC "YYYY-MM-DDTHH:II:SSZ") | |
batch_date .end_date | string | "" | Searches by batch_date between the provided start_date and end_date. (Dates in UTC "YYYY-MM-DDTHH:II:SSZ") | |
settlement_batch_id | object | Object containing details defining a range of id's | ||
settlement_batch_id .operator | string literal | "=" or "!=" | ||
settlement_batch_id .value | string | The settlement batch id to match or exclude | ||
limit | integer | 10 | The number of results to return (1-100) | |
offset | integer | 0 | The number of results to skip (1-1000) |
File Batch
Upload File
Upload a CSV file for batch processing.
TIP
CSV File Format
The input file for the upload endpoint should contain records to process in the following format (example below):
- First row should be a header using the fields below, fields can be in any order and not all fields are required.
- Each field should be wrapped in quotes and should not contain any quotes
- Each field should be seperated with a comma
- Each row should be terminated with a newline \n character.
Request Method:
POST
URL Endpoint:
/api/filebatch
Name | Type | Default | Description | Required |
---|---|---|---|---|
transaction_type | string | "verification", "authorize", "capture", "sale", "credit" or "refund" | * | |
cc_number | string | CC Number | if credit card | |
cc_expiration | string | CC Expiration Date | if credit card | |
cc_cvc | string | Optional unless your account requires CVC for processing | ||
ach_account_number | string | ACH account number | if ACH | |
ach_routing_number | string | ACH routing number | if ACH | |
ach_account_type | string | "checking" or "savings" | if ACH | |
ach_sec_code | string | SEC code: "WEB", "CCD", or "PPD" | if ACH | |
customer_id | string | customer vault id to charge | if using customer vault | |
amount | integer | Total amount to process in cents (100 = $1.00) | * | |
shipping_amount | integer | Shipping amount to process in cents (100 = $1.00) | ||
tax_amount | integer | Tax amount to process in cents (100 = $1.00) | ||
discount_amount | integer | Discount amount to process in cents (100 = $1.00) | ||
order_id | string | Alphanumeric string for reference (max 17 characters) | ||
description | string | Alphanumeric string for notes (max 100 characters) | ||
po_number | string | Alphanumeric string for reference (max 17 characters) | ||
tax_exempt | boolean | false | is the transaction tax exempt | |
email_address | string | Email address to tag to the transaction, emails are not sent. | ||
processor_id | string | Processor ID to process the transaction, otherwise the default is used. | ||
billing_first_name | string | |||
billing_last_name | string | |||
billing_company | string | |||
billing_address_line_1 | string | |||
billing_address_line_2 | string | |||
billing_city | string | |||
billing_state | string | |||
billing_postal_code | string | |||
billing_country | string | |||
billing_phone | string | |||
billing_fax | string | |||
billing_email | string | |||
shipping_first_name | string | |||
shipping_last_name | string | |||
shipping_company | string | |||
shipping_address_line_1 | string | |||
shipping_address_line_2 | string | |||
shipping_city | string | |||
shipping_state | string | |||
shipping_postal_code | string | |||
shipping_country | string | |||
shipping_phone | string | |||
shipping_fax | string | |||
shipping_email | string |
Get Status
Get the current status of a specified settlement batch.
Request Method:
GET
URL Endpoint:
/api/filebatch/{ batch id }
js
function getBatchStatus(batchId) {
var myHeaders = new Headers();
myHeaders.append("Authorization", apiKey);
myHeaders.append("Content-Type", "application/json");
var requestOptions = {
method: "GET",
headers: myHeaders,
};
fetch("https://sandbox.pepperpaygateway.com/api/filebatch/" + batchId, requestOptions)
.then((response) => response.text())
.then((result) => {
if (result.status === "success") {
// handle success
var message = result.msg;
} else {
// handle non success
}
})
.catch((error) => console.log("error", error));
}
Download File
Returns a CSV text response for the specified batch.
Request Method:
GET
URL Endpoint:
/api/filebatch/{ batch id }/download
js
function downloadBatchFile(batchId) {
var myHeaders = new Headers();
myHeaders.append("Authorization", apiKey);
myHeaders.append("Content-Type", "application/json");
var requestOptions = {
method: "GET",
headers: myHeaders,
};
fetch(
"https://sandbox.pepperpaygateway.com/api/filebatch/" + batchId + "/download",
requestOptions
)
.then((response) => {
if (response.ok) {
return response.text().then((csvData) => {
// return csv file.. csvData
});
} else {
return response.text().then((result) => {
var msg = result.msg;
});
}
})
.catch((error) => console.log("error", error));
}
Recurring
Add-Ons
Add-ons are used to adjust a recurring charge amount, either by a set amount or a percentage of the subscription amount.
Create Add-On
Create a new recurring plan add-on.
Request Method:
POST
URL Endpoint:
/api/recurring/addon
Name | Type | Default | Description | Required |
---|---|---|---|---|
name | string | "" | Display name for the add-on | |
description | string | "" | Description for the add-on | |
amount | integer | null | Amount to be added in cents (100 = $1.00) | * (see note below) |
percentage | integer | null | Percentage of original charge to be added (must be 0 or a percentage between .1% and 100%, expressed in thousandths. 43440 = 43.440%) | * (see note below) |
duration | integer | 0 | Number of times for the add-on to be billed (use 0 if you want the add-on to persist until cancelled) |
TIP
Either amount or percentage may be provided, but not both.
Get Add-On By ID
Retrieve details for the specified add-on.
Request Method:
GET
URL Endpoint:
/api/recurring/addon/{ add-on id }
json
{
"status": "success",
"msg": "success",
"data": {
"id": "b89ffdqj8m0o735i19i0",
"name": "test plan",
"description": "just a simple test plan",
"amount": 100,
"percentage": null,
"duration": 0,
"created_at": "2017-11-20T15:41:43.330315Z",
"updated_at": "2017-11-20T15:41:43.330315Z"
}
}
Get All Add-Ons
Retrieve details for all add-ons accosciated with the gateway account.
Request Method:
GET
URL Endpoint:
/api/recurring/addons
json
{
"status": "success",
"msg": "success",
"data": [
{
"id": "b75cvl51tlv38t0o7o30",
"name": "test_addon",
"description": "some description",
"amount": 100,
"percentage": null,
"duration": 0,
"created_at": "2017-09-26T22:08:20Z",
"updated_at": "2017-09-26T22:08:20Z"
},
{
"id": "b779mpt1tlv96kdv2n20",
"name": "test_addon_percent",
"description": "",
"amount": null,
"percentage": 10,
"duration": 0,
"created_at": "2017-10-09T20:39:41Z",
"updated_at": "2017-10-09T20:39:41Z"
},
{
"id": "b89ffdqj8m0o735i19i0",
"name": "test plan",
"description": "just a simple test plan",
"amount": 100,
"percentage": null,
"duration": 0,
"created_at": "2017-11-20T15:41:43Z",
"updated_at": "2017-11-20T15:41:43Z"
}
],
"total_count": 3
}
Update Add-On
Edit details for the specified add-on.
Request Method:
POST
URL Endpoint:
/api/recurring/addon/{ add-on id }
Name | Type | Default | Description | Required |
---|---|---|---|---|
name | string | "" | Display name for the add-on | |
description | string | "" | Description for the add-on | |
amount | integer | null | Amount to be added in cents (100 = $1.00) | * (see note below) |
percentage | integer | null | Percentage of original charge to be added (must be 0 or a percentage between .1% and 100%, expressed in thousandths. 43440 = 43.440%) | * (see note below) |
duration | integer | 0 | Number of times for the add-on to be billed (use 0 if you want the subscription to persist until cancelled) |
TIP
Either amount or percentage may be provided, but not both.
Delete Add-On
Delete the specified add-on.
Request Method:
DELETE
URL Endpoint:
/api/recurring/addon/{ add-on id }
json
{
"status": "success",
"msg": "success",
"data": null
}
Discounts
Create Discount
Create a new recurring plan discount. Discounts are used to adjust a recurring charge amount either by a set amount or a percentage of the subscription amount.
Request Method:
POST
URL Endpoint:
/api/recurring/discount
Name | Type | Default | Description | Required |
---|---|---|---|---|
name | string | "" | Display name for the discount | |
description | string | "" | Description for the discount | |
amount | integer | null | Amount to be discounted in cents (100 = $1.00) | * (see note below) |
percentage | integer | null | Percentage of original charge to be discounted (must be 0 or a percentage between .1% and 100%, expressed in thousandths. 43440 = 43.440%) | * (see note below) |
duration | integer | 0 | Number of times for the discount to be billed (use 0 if you want the discount to persist until cancelled) |
TIP
Either amount or percentage may be provided, but not both.
Get Discount By ID
Retrieve details for the specified discount.
Request Method:
GET
URL Endpoint:
/api/recurring/discount/{ discount id }
json
{
"status": "success",
"msg": "success",
"data": {
"id": "b89flfqj8m0o735i19ig",
"name": "test discount",
"description": "just a simple test discount",
"amount": 100,
"percentage": null,
"duration": 0,
"created_at": "2017-11-20T15:54:39.851636Z",
"updated_at": "2017-11-20T15:54:39.851636Z"
}
}
Get All Discounts
Retrieve the properties of all discounts for the gateway account associated with the API Key or JWT token provided in the Authorization header.
Request Method:
GET
URL Endpoint:
/api/recurring/discounts
json
{
"status": "success",
"msg": "success",
"data": [
{
"id": "b89flfqj8m0o735i19ig",
"name": "test discount",
"description": "just a simple test discount",
"amount": 100,
"percentage": null,
"duration": 0,
"created_at": "2017-11-20T15:54:40Z",
"updated_at": "2017-11-20T15:54:40Z"
},
{
"id": "b779mpt1tlv96kdv2n20",
"name": "test_discount_percent",
"description": "",
"amount": null,
"percentage": 10,
"duration": 0,
"created_at": "2017-10-09T20:59:52Z",
"updated_at": "2017-10-09T20:59:52Z"
}
],
"total_count": 2
}
Update Discount
Edit details for the specified discount.
Request Method:
POST
URL Endpoint:
/api/recurring/discount/{ discount id }
Name | Type | Default | Description | Required |
---|---|---|---|---|
name | string | "" | Display name for the discount | |
description | string | "" | Description for the discount | |
amount | integer | null | Amount to be discounted in cents (100 = $1.00) | * (see note below) |
percentage | integer | null | Percentage of original charge to be discounted (must be 0 or a percentage between .1% and 100%, expressed in thousandths. 43440 = 43.440%) | * (see note below) |
duration | integer | 0 | Number of times for the discount to be billed (use 0 if you want the discount to persist until cancelled) |
TIP
Either amount or percentage may be provided, but not both.
Delete Discount
Delete the specified discount.
Request Method:
DELETE
URL Endpoint:
/api/recurring/discount/{ discount id }
json
{
"status": "success",
"msg": "success",
"data": null
}
Plans
Create Plan
Creates a new recurring plan with discounts and/or add-ons.
Request Method:
POST
URL Endpoint:
/api/recurring/plan
Name | Type | Default | Description | Required |
---|---|---|---|---|
name | string | "" | Display name for the plan | * |
description | string | "" | Description for the plan | |
amount | integer | null | Amount to be billed in cents (100 = $1.00) | * |
billing_cycle_interval | integer | null | How often to run the billing cycle (run every X months) | * |
billing_frequency | string literal | "monthly" | How often to run the plan within a billing cycle. ("monthly", "twice_monthly", "daily") | * |
billing_days | string | null | Which day of the month to bill on. If "twice_monthly" then comma separate dates ("1, 15"). For the last day of the month, use "0". | * |
duration | integer | 0 | Number of times for the plan to be billed (use 0 if you want the plan to persist until cancelled) | |
add_ons | array of objects | Enumerates add-ons for a recurring plan | ||
add_ons[#] .id | string | ID of the referenced add_on | ||
add_ons[#] .name | string | Display name for the add_on (optional, this overrides the add_ons value) | ||
add_ons[#] .description | string | Description for the add_on (optional, this overrides the add_ons value) | ||
add_ons[#] .amount | int | Amount to be added (optional, this overrides the add_ons value) | ||
add_ons[#] .duration | int | Duration for the add_on to be billed (optional, this overrides the add_ons value) | ||
discounts | array of objects | Enumerates discounts for a recurring plan | ||
discounts[#] .id | string | ID of the referenced discount | ||
discounts[#] .name | string | Display name for the discount (optional, this overrides the discount value) | ||
discounts[#] .description | string | Description for the discount (optional, this overrides the discount value) | ||
discounts[#] .amount | int | Amount to be discounted (optional, this overrides the discount value) | ||
discounts[#] .duration | int | Duration for the discount to be billed (optional, this overrides the discount value) |
Get Plan By ID
Retrieve details for the specified plan.
Request Method:
GET
URL Endpoint:
/api/recurring/plan/{ plan id }
json
{
"status": "success",
"msg": "success",
"data": {
"id": "b89g35qj8m0o735i19jg",
"name": "test plan",
"description": "just a simple test plan",
"amount": 100,
"billing_cycle_interval": 1,
"billing_frequency": "twice_monthly",
"billing_days": "1,15",
"total_add_ons": 100,
"total_discounts": 50,
"duration": 0,
"add_ons": [
{
"id": "b75cvl51tlv38t0o7o30",
"name": "test_addon",
"description": "this will add to the cost of the subscription",
"amount": 100,
"percentage": null,
"duration": 0,
"created_at": null,
"updated_at": null
}
],
"discounts": [
{
"id": "b89flfqj8m0o735i19ig",
"name": "test discount",
"description": "this will discount the cost of the subscription",
"amount": 50,
"percentage": null,
"duration": 0,
"created_at": null,
"updated_at": null
}
],
"created_at": "2017-11-20T16:23:51.990051Z",
"updated_at": "2017-11-20T16:23:51.990051Z"
}
}
Get All Plans
Retrieve the properties of all plans for the gateway account associated with the API Key or JWT token provided in the Authorization header.
Request Method:
GET
URL Endpoint:
/api/recurring/plans
json
{
"status": "success",
"msg": "success",
"data": [
{
"id": "b89g35qj8m0o735i19jg",
"name": "test plan",
"description": "just a simple test plan",
"amount": 100,
"billing_cycle_interval": 1,
"billing_frequency": "twice_monthly",
"billing_days": "1,15",
"total_add_ons": 100,
"total_discounts": 50,
"duration": 0,
"add_ons": [
{
"id": "b75cvl51tlv38t0o7o30",
"name": "test_addon",
"description": "this will add to the cost of the subscription",
"amount": 100,
"percentage": null,
"duration": 0,
"created_at": null,
"updated_at": null
}
],
"discounts": [
{
"id": "b89flfqj8m0o735i19ig",
"name": "test discount",
"description": "this will discount the cost of the subscription",
"amount": 50,
"percentage": null,
"duration": 0,
"created_at": null,
"updated_at": null
}
],
"created_at": "2017-11-20T16:23:52Z",
"updated_at": "2017-11-20T16:23:52Z"
}
],
"total_count": 1
}
Update Plan
Edit details for the specified plan.
Request Method:
POST
URL Endpoint:
/api/recurring/plan/{ plan id }
Name | Type | Default | Description | Required |
---|---|---|---|---|
name | string | "" | Display name for the plan | * |
description | string | "" | Description for the plan | |
amount | integer | null | Amount to be billed in cents (100 = $1.00) | * |
billing_cycle_interval | integer | null | How often to run the billing cycle (run every X months) | * |
billing_frequency | string literal | "monthly" | How often to run the plan within a billing cycle. ("monthly", "twice_monthly", "daily") | * |
billing_days | string | null | Which day of the month to bill on. If "twice_monthly" then comma separate dates ("1, 15"). For the last day of the month, use "0". | * |
duration | integer | 0 | Number of times for the plan to be billed (use 0 if you want the plan to persist until cancelled) | |
add_ons | array of objects | Enumerates add-ons for a recurring plan | ||
add_ons[#] .id | string | ID of the referenced add_on | ||
add_ons[#] .name | string | Display name for the add_on (optional, this overrides the add_ons value) | ||
add_ons[#] .description | string | Description for the add_on (optional, this overrides the add_ons value) | ||
add_ons[#] .amount | int | Amount to be added (optional, this overrides the add_ons value) | ||
add_ons[#] .duration | int | Duration for the add_on to be billed (optional, this overrides the add_ons value) | ||
discounts | array of objects | Enumerates discounts for a recurring plan | ||
discounts[#] .id | string | ID of the referenced discount | ||
discounts[#] .name | string | Display name for the discount (optional, this overrides the discount value) | ||
discounts[#] .description | string | Description for the discount (optional, this overrides the discount value) | ||
discounts[#] .amount | int | Amount to be discounted (optional, this overrides the discount value) | ||
discounts[#] .duration | int | Duration for the discount to be billed (optional, this overrides the discount value) |
Delete Plan
Delete the specified plan.
Request Method:
DELETE
URL Endpoint:
/api/recurring/plan/{ plan id }
json
{
"status": "success",
"msg": "success",
"data": null
}
Subscriptions
Create Subscription
Creates a new subscription which applies a recurring billing plan to a customer.
Request Method:
POST
URL Endpoint:
/api/recurring/subscription
Name | Type | Default | Description | Required |
---|---|---|---|---|
plan_id | string | "" | ID of the plan being subscribed to | |
description | string | "" | Description for the subscription | |
customer | object | Object containing details for the customer being subscribed to the plan | ||
customer .id | string | ID for the customer being subscribed to the billing plan | * | |
customer .payment_method_type | string | default payment method type | "card" or "ach" | |
customer .payment_method_id | string | default payment method id | ID of the customer's saved payment method to use for the billing plan | required if payment_method_type is present |
customer .billing_address_id | string | default billing address | ID of the customer's saved billing address to use for the billing plan | |
customer .shipping_address_id | string | default shipping address | ID of the customer's saved shipping address to use for the billing plan | |
amount | integer | null | Amount to be billed in cents (100 = $1.00) | * |
billing_cycle_interval | integer | null | How often to run the billing cycle (run every X months) | * |
billing_frequency | string literal | "monthly" | How often to run the subscription within a billing cycle. ("monthly", "twice_monthly", "daily") | * |
billing_days | string | null | Which day of the month to bill on. If "twice_monthly" then comma separate dates ("1, 15"). For the last day of the month, use "0". | * |
duration | integer | 0 | Number of times for the subscription to be billed (use 0 if you want the subscription to persist until cancelled) | |
next_bill_date | string "YYYY-MM-DD" | The date of the next time the billing plan will be processed | ||
add_ons | array of objects | Enumerates add-ons for a recurring subscription | ||
add_ons[#] .id | string | ID of the referenced add_on | ||
add_ons[#] .name | string | Display name for the add_on (optional, this overrides the add_ons value) | ||
add_ons[#] .description | string | Description for the add_on (optional, this overrides the add_ons value) | ||
add_ons[#] .amount | int | Amount to be added (optional, this overrides the add_ons value) | ||
add_ons[#] .duration | int | Duration for the add_on to be billed (optional, this overrides the add_ons value) | ||
discounts | array of objects | Enumerates discounts for a recurring subscription | ||
discounts[#] .id | string | ID of the referenced discount | ||
discounts[#] .name | string | Display name for the discount (optional, this overrides the discount value) | ||
discounts[#] .description | string | Description for the discount (optional, this overrides the discount value) | ||
discounts[#] .amount | int | Amount to be discounted (optional, this overrides the discount value) | ||
discounts[#] .duration | int | Duration for the discount to be billed (optional, this overrides the discount value) |
Get Subscription By ID
Retrieve details for the specified subscription.
Request Method:
GET
URL Endpoint:
/api/recurring/subscription/{ subscription id }
json
{
"status": "success",
"msg": "success",
"data": {
"id": "b89gftaj8m0oft7upk80",
"plan_id": "b89g35qj8m0o735i19jg",
"description": "some description to describe the subscription",
"customer": {
"id": "b81ko5qq9qq5v460r9i0",
"payment_method_type": "card",
"payment_method_id": "b81ko5qq9qq5v460r9i0",
"billing_address_id": "b81ko5qq9qq5v460r9i0",
"shipping_address_id": "b81ko5qq9qq5v460r9i0"
},
"amount": 100,
"total_adds": 0,
"total_discounts": 50,
"billing_cycle_interval": 1,
"billing_frequency": "twice_monthly",
"billing_days": "1,15",
"duration": 0,
"next_bill_date": "2017-11-22",
"add_ons": null,
"discounts": [
{
"id": "b89flfqj8m0o735i19ig",
"description": "this will discount the cost of the subscription",
"amount": 50,
"percentage": null,
"duration": 0
}
],
"created_at": "2017-11-20T16:51:01.798736Z",
"updated_at": "2017-11-20T16:51:01.798736Z"
}
}
Update Subscription
Edit details for the specified subscription.
Request Method:
POST
URL Endpoint:
/api/recurring/subscription/{ subscription id }
Name | Type | Default | Description | Required |
---|---|---|---|---|
plan_id | string | "" | ID of the plan being subscribed to | |
description | string | "" | Description for the subscription | |
customer | object | Object containing details for the customer being subscribed to the plan | ||
customer .id | string | ID for the customer being subscribed to the billing plan | * | |
customer .payment_method_type | string | default payment method type | "card" or "ach" | |
customer .payment_method_id | string | default payment method id | ID of the customer's saved payment method to use for the billing plan | required if payment_method_type is present |
customer .billing_address_id | string | default billing address | ID of the customer's saved billing address to use for the billing plan | |
customer .shipping_address_id | string | default shipping address | ID of the customer's saved shipping address to use for the billing plan | |
amount | integer | null | Amount to be billed in cents (100 = $1.00) | * |
billing_cycle_interval | integer | null | How often to run the billing cycle (run every X months) | * |
billing_frequency | string literal | "monthly" | How often to run the subscription within a billing cycle. ("monthly", "twice_monthly", "daily") | * |
billing_days | string | null | Which day of the month to bill on. If "twice_monthly" then comma separate dates ("1, 15"). For the last day of the month, use "0". | * |
duration | integer | 0 | Number of times for the subscription to be billed (use 0 if you want the subscription to persist until cancelled) | |
next_bill_date | string "YYYY-MM-DD" | The date of the next time the billing plan will be processed | ||
add_ons | array of objects | Enumerates add-ons for a recurring subscription | ||
add_ons[#] .id | string | ID of the referenced add_on | ||
add_ons[#] .name | string | Display name for the add_on (optional, this overrides the add_ons value) | ||
add_ons[#] .description | string | Description for the add_on (optional, this overrides the add_ons value) | ||
add_ons[#] .amount | int | Amount to be added (optional, this overrides the add_ons value) | ||
add_ons[#] .duration | int | Duration for the add_on to be billed (optional, this overrides the add_ons value) | ||
discounts | array of objects | Enumerates discounts for a recurring subscription | ||
discounts[#] .id | string | ID of the referenced discount | ||
discounts[#] .name | string | Display name for the discount (optional, this overrides the discount value) | ||
discounts[#] .description | string | Description for the discount (optional, this overrides the discount value) | ||
discounts[#] .amount | int | Amount to be discounted (optional, this overrides the discount value) | ||
discounts[#] .duration | int | Duration for the discount to be billed (optional, this overrides the discount value) |
Pause Subscription
Pause the specified subscription.
Request Method:
GET
URL Endpoint:
/api/recurring/subscription/{ subscription id }/status/paused
json
{
"status": "success",
"msg": "success",
"data": {
"id": "cn9rrqbug2jpf9mtp6c0",
"plan_id": "cn9rrkrug2jpf9mtp6bg",
"plan_name": "",
"status": "paused",
"description": "",
"customer_name": "",
"shared": false,
"customer": {
"id": "cn9nrfbug2jpejn1kbeg",
"payment_method_type": "",
"payment_method_id": "",
"billing_address_id": "",
"shipping_address_id": ""
},
"amount": 100,
"currency": "USD",
"processor_id": "",
"total_adds": 0,
"total_discounts": 0,
"billing_cycle_interval": 1,
"billing_frequency": "monthly",
"billing_days": "1",
"duration": 0,
"next_bill_date": "2024-02-19",
"add_ons": null,
"discounts": null,
"expiration_date": "",
"events": null,
"created_at": "2024-02-19T20:45:30Z",
"updated_at": "2024-02-19T20:45:50.953717Z",
"charge_on_day": false
}
}
Mark Subscription Past Due
Mark the specified subscription as past due.
Request Method:
GET
URL Endpoint:
/api/recurring/subscription/{ subscription id }/status/past_due
json
{
"status": "success",
"msg": "success",
"data": {
"id": "cnb14e3ug2jpf9mtp6k0",
"plan_id": "cn9rrkrug2jpf9mtp6bg",
"plan_name": "",
"status": "past_due",
"description": "",
"customer_name": "",
"shared": false,
"customer": {
"id": "cn9nrfbug2jpejn1kbeg",
"payment_method_type": "",
"payment_method_id": "",
"billing_address_id": "",
"shipping_address_id": ""
},
"amount": 100,
"currency": "USD",
"processor_id": "",
"total_adds": 0,
"total_discounts": 0,
"billing_cycle_interval": 1,
"billing_frequency": "monthly",
"billing_days": "1",
"duration": 0,
"next_bill_date": "2024-02-21",
"add_ons": null,
"discounts": null,
"expiration_date": "",
"events": null,
"created_at": "2024-02-21T15:09:45Z",
"updated_at": "2024-02-21T15:13:03.001456Z",
"charge_on_day": false
}
}
Cancel Subscription
Cancel the specified subscription.
Request Method:
GET
URL Endpoint:
/api/recurring/subscription/{ subscription id }/status/cancelled
json
{
"status": "success",
"msg": "success",
"data": {
"id": "cn9rrqbug2jpf9mtp6c0",
"plan_id": "cn9rrkrug2jpf9mtp6bg",
"plan_name": "",
"status": "cancelled",
"description": "",
"customer_name": "",
"shared": false,
"customer": {
"id": "cn9nrfbug2jpejn1kbeg",
"payment_method_type": "",
"payment_method_id": "",
"billing_address_id": "",
"shipping_address_id": ""
},
"amount": 100,
"currency": "USD",
"processor_id": "",
"total_adds": 0,
"total_discounts": 0,
"billing_cycle_interval": 1,
"billing_frequency": "monthly",
"billing_days": "1",
"duration": 0,
"next_bill_date": "2024-02-19",
"add_ons": null,
"discounts": null,
"expiration_date": "",
"events": null,
"created_at": "2024-02-19T20:45:30Z",
"updated_at": "2024-02-19T21:05:39.561726Z",
"charge_on_day": false
}
}
Activate Subscription
Activate the specified subscription.
Request Method:
GET
URL Endpoint:
/api/recurring/subscription/{ subscription id }/status/active
Query Params
Name | Default | Description |
---|---|---|
next_bill_date | Date in 'YYYY-MM-DD' format |
json
{
"status": "success",
"msg": "success",
"data": {
"id": "cn9rrqbug2jpf9mtp6c0",
"plan_id": "cn9rrkrug2jpf9mtp6bg",
"plan_name": "",
"status": "active",
"description": "",
"customer_name": "",
"shared": false,
"customer": {
"id": "cn9nrfbug2jpejn1kbeg",
"payment_method_type": "",
"payment_method_id": "",
"billing_address_id": "",
"shipping_address_id": ""
},
"amount": 100,
"currency": "USD",
"processor_id": "",
"total_adds": 0,
"total_discounts": 0,
"billing_cycle_interval": 1,
"billing_frequency": "monthly",
"billing_days": "1",
"duration": 0,
"next_bill_date": "2024-02-19",
"add_ons": null,
"discounts": null,
"expiration_date": "",
"events": null,
"created_at": "2024-02-19T20:45:30Z",
"updated_at": "2024-02-19T21:10:36.976006Z",
"charge_on_day": false
}
}
Complete Subscription
Complete the specified subscription.
Request Method:
GET
URL Endpoint:
/api/recurring/subscription/{ subscription id }/status/completed
json
{
"status": "success",
"msg": "success",
"data": {
"id": "cn9rrqbug2jpf9mtp6c0",
"plan_id": "cn9rrkrug2jpf9mtp6bg",
"plan_name": "",
"status": "completed",
"description": "",
"customer_name": "",
"shared": false,
"customer": {
"id": "cn9nrfbug2jpejn1kbeg",
"payment_method_type": "",
"payment_method_id": "",
"billing_address_id": "",
"shipping_address_id": ""
},
"amount": 100,
"currency": "USD",
"processor_id": "",
"total_adds": 0,
"total_discounts": 0,
"billing_cycle_interval": 1,
"billing_frequency": "monthly",
"billing_days": "1",
"duration": 0,
"next_bill_date": "2024-02-19",
"add_ons": null,
"discounts": null,
"expiration_date": "",
"events": null,
"created_at": "2024-02-19T20:45:30Z",
"updated_at": "2024-02-19T21:25:01.161503Z",
"charge_on_day": false
}
}
Delete Subscription
Delete the specified subscription.
Request Method:
DELETE
URL Endpoint:
/api/recurring/subscription/{ subscription id }
json
{
"status": "success",
"msg": "success",
"data": null
}
Terminals
All transaction requests should be processed via the /transaction
endpoint referencing the specific terminal to handle the request. Please see the Processing a Transaction section for more information.
Get All Terminals
Retrieve all terminals associated with the gateway account. This will include inactive/disabled terminals as well.
Request Method:
GET
URL Endpoint:
/api/terminals
json
{
"status": "success",
"msg": "",
"total_count": 1,
"data": [
{
"id": "1ucio551tlv85l7moe5s",
"merchant_id": "aucio551tlv85l7moe5g",
"manufacturer": "dejavoo",
"model": "z11",
"serial_number": "1811000XXXX",
"tpn": "1811000XXXX",
"description": "front counter z11",
"status": "active",
"auth_key": "wcR1c9o1",
"register_id": "1",
"auto_settle": true,
"settle_at": "00:00:00",
"created_at": "2018-01-12T03:57:59Z",
"updated_at": "0001-01-01T00:00:00Z"
}
]
}
Invoices
TIP
The invoice ID will be set to the following fields on a transaction when paid:
- Order ID
- PO number
This will allow you to look up a transaction by an invoice ID and vice versa. If you set the invoice number field on an invoice, then the transaction order ID field will be this invoice number in place of the invoice ID.
Create Invoice
Create a new invoice.
Request Method:
POST
URL Endpoint:
/api/invoice
Name | Type | Default | Description | Required |
---|---|---|---|---|
currency | string literal | Currency that invoice amounts should be in ("USD", etc.) | * | |
company_name | string | Name of company issuing the invoice | ||
company_logo_url | string | Hosted location of logo image to include on invoice | ||
customer_number | string | Optional identifier for the invoiced customer to match merchant records | ||
customer_id | string | ID of the saved customer being invoiced (must be a valid customer id if included) | ||
invoice_number | string | Optional identifier for the invoice to match merchant records | ||
payable_to | object | object containing details for the person the invoice is being paid to | * | |
payable_to .id | string | ID of the stored address you want to make the invoice payable to | ||
payable_to .first_name | string | First name | ||
payable_to .last_name | string | Last name | ||
payable_to .company | string | Company name | ||
payable_to .address_line_1 | string | Address line 1 | * | |
payable_to .address_line_2 | string | Address line 2 | ||
payable_to .city | string | City | * | |
payable_to .state | string literal | State, in 2-character format ("KS", "QC", etc.)) | * | |
payable_to .postal_code | string | Postal code (must be a valid postal code for the country provided) | * | |
payable_to .country | string literal | Country, in 2-character format ("US", "CA", "MX", etc.) | * | |
payable_to .phone | string | Phone number | ||
payable_to .fax | string | Fax number | ||
payable_to | string | Email address (must be valid email format, "example@mail.com") | ||
bill_to | object | object containing details for the person the invoice is being billed to | * | |
bill_to .id | string | ID of the stored address you want to make the invoice billable to | ||
bill_to .first_name | string | First name | ||
bill_to .last_name | string | Last name | ||
bill_to .company | string | Company name | ||
bill_to .address_line_1 | string | Address line 1 | * | |
bill_to .address_line_2 | string | Address line 2 | ||
bill_to .city | string | City | * | |
bill_to .state | string literal | State, in 2-character ("KS", "QC", etc.)format | * | |
bill_to .postal_code | string | Postal (must be a valid postal code for the country provided) code | * | |
bill_to .country | string literal | Country, in 2-character ("US", "CA", "MX", etc.) format | * | |
bill_to .phone | string | Phone number | ||
bill_to .fax | string | Fax number | ||
bill_to | string | Email address (must be valid email format, "example@mail.com") | ||
date_due | datetime string | Date the invoice is due ("2021-02-13T06:00:00.000Z")by | * | |
items[#] | object array | array containing line items included in the invoice | * | |
items[#] .status | string literal | "pending" or "paid" | * | |
items[#] .type | string | "" | Type of item | |
items[#] .name | string | "" | Name of item | |
items[#] .description | string | "" | Description of item | |
items[#] .unit_price | integer | Unit price of item | * | |
items[#] .quantity | integer | Quantity of item | * | |
items[#] .quantity_shipped | integer | 0 | Quantity of items shipped to customer | |
items[#] .product_code | string | "" | Product Code of item | |
items[#] .commodity_code | string | "" | Commodity Code of item | |
items[#] .unit_of_measure | string | "" | Unit of measure of item ("lb", "kg", etc.) | |
items[#] .alternate_tax_identifier | string | "" | Alternate tax ID for item | |
items[#] .taxable | boolean | false | Whether local and national tax should be applied at the item level rather than the invoice level | |
items[#] .local_tax_rate | string | "" | Local tax rate for item ("1.000") | |
items[#] .local_tax | integer | 0 | Local tax amount to be added to the item's total, expressed in cents (100 = $1.00) | |
items[#] .national_tax_rate | string | "" | National tax rate for item ("1.000") | |
items[#] .national_tax | integer | 0 | National tax amount to be added to the item's total, expressed in cents (100 = $1.00) | |
items[#] .tax_rate | string | "" | Combined tax rate for item (local tax + national tax) | |
items[#] .tax_amount | integer | 0 | Tax amount to be added to the item's total, expressed in cents (100 = $1.00) | |
items[#] .discount_amount | integer | 0 | Discount to take off the item's total amount, expressed in cents (100 = $1.00)) | |
items[#] .freight_amount | integer | 0 | Freight amount to add to the item's total, expressed in cents (100 = $1.00) | |
advanced_fields | boolean | false | Whether or not to include additional fields for line items (advanced fields include quantity_shipped, freight_amount, unit_of_measure, taxable, local_tax_rate, local_tax, national_tax_rate, national_tax) | |
enable_tax | boolean | false | Whether or not to enable tax (if enabled, tax applied at the invoice level will override taxes applied at the item level) | |
enable_shipping | boolean | false | Whether or not to enable shipping | |
require_shipping_details | boolean | false | Whether or not to require shipping details | |
require_billing_details_on_payment_only | boolean | false | Whether or not to require billing details only at time of payment | |
tax_percent | string | Tax rate to apply to invoice total if enable_tax is true. A rate of "0.000" will cause tax to be read as a flat amount. | * | |
tax | integer | calculated amount | Total tax amount of the invoice, expressed in cents (100 = $1.00). If tax_percent is included and is not "0", this field will be overridden with the calculated amount. | |
shipping | integer | calculated amount | Shipping amount of the invoice, expressed in cents (100 = $1.00) | |
amount_paid | integer | calculated amount | Amount of the invoice that has already been paid, expressed in cents (100 = $1.00) | |
service_fees_paid | integer | calculated amount | Service fee amount that has already been paid, expressed in cents (100 = $1.00) | |
surcharge_paid | integer | calculated amount | Surcharge amount that has already been paid, expressed in cents (100 = $1.00) | |
discount_credited | integer | calculated amount | Discount amount that has already been credited, expressed in cents (100 = $1.00) | |
adjustment | integer | 0 | Apply a payment adjustment to the total amount of the invoice, expressed in cents (100 = $1.00) | |
allow_partial_payment | boolean | false | Whether or not to allow partial payment of the amount due | |
transaction_type | string literal | "sale" | "sale" or "authorize" | |
payment_methods[#] | string array | Allowable payment method types ("card", "ach", and/or "mail") | * | |
card_processor_id (can be "") | string | ID of the payment processor to use for credit card payments | * | |
ach_processor_id (can be "") | string | ID of the payment processor to use for ACH payments | * | |
message | string | Message for customers viewing the invoice | ||
send_via | string literal | How to send invoice notifications ("email", "text", "both", or "none") | * | |
email_to | string | Email address (must be valid email format, "xxxxx@xxxxx.xxx") |
Get Invoice By ID
Retrieve details for the specified invoice.
Request Method:
GET
URL Endpoint:
/api/invoice/{ invoice id }
json
{
"status": "success",
"msg": "success",
"data": {
"id": "bhi9vado3hogrne0u4tg",
"currency": "USD",
"company_name": "ACME Inc.",
"company_logo_url": "",
"customer_number": "123Customer",
"payable_to": {
"id": "",
"first_name": "First",
"last_name": "Last",
"company": "Merchant Business",
"address_line_1": "123 Some St",
"address_line_2": "",
"city": "Some City",
"state": "IL",
"postal_code": "60000",
"country": "US",
"phone": "5555555555",
"fax": "5555555555",
"email": "info@somewebsite.com"
},
"bill_to": {
"id": "",
"first_name": "First",
"last_name": "Last",
"company": "Some Business",
"address_line_1": "123 Drury Lane",
"address_line_2": "",
"city": "Some City",
"state": "IL",
"postal_code": "60000",
"country": "US",
"phone": "5555555555",
"fax": "5555555555",
"email": "info@somesite.com"
},
"created_at": "2019-02-13T22:52:26Z",
"date_due": "2019-02-13T06:00:00Z",
"items": [
{
"id": "bhi9vado3hogrne0u4t0",
"name": "Widget",
"description": "A widget for processors",
"quantity": 1,
"quantity_shipped": 0,
"unit_of_measure": "",
"unit_price": 100,
"discount": 0,
"discount_type": "$",
"taxable": false,
"local_tax": "0",
"national_tax": "0",
"tax_rate": "0",
"tax_amount": 0,
"amount": 100,
"status": "pending"
}
],
"advanced_fields": false,
"subtotal": 100,
"tax_percent": "0.00",
"tax": 0,
"total": 100,
"amount_paid": 0,
"adjustment": 0,
"amount_due": 100,
"payment_methods": ["card"],
"card_processor_id": "bhi5qa5o3hogms88jojg",
"ach_processor_id": "",
"status": "pending",
"message": "Thank you for your business!",
"reject_message": "",
"send_via": "none",
"last_sent_at": "0001-01-01T00:00:00Z",
"updated_at": "2019-02-13T23:15:43Z",
"public_url": "d038ea94-3f4f-4703-9e94-74792605944e",
"hosted_url": "http://localhost:8080/invoice/d038ea94-3f4f-4703-9e94-74792605944e"
}
}
Search Invoices
Retrieve details for all invoices that match provided search criteria.
Request Method:
POST
URL Endpoint:
/api/invoices/search
Name | Type | Description |
---|---|---|
id | object | Object containing details for searching by id |
id .operator | string literal | "=" or "!=" |
id .value | string | invoice id to match or exclude |
amount_due | object | Object containing details for searching by amount_due |
amount_due .operator | string literal | "=", "!=", "<", or ">" |
amount_due .value | integer | amount to match or exclude |
date_due | object | Object containing details for searching by date_due |
date_due .start_date | date string | Searches by date_due between the provided start_date and end_date. (Dates in UTC "YYYY-MM-DDTHH:II:SSZ") |
date_due .end_date | date string | Searches by date_due between the provided start_date and end_date. (Dates in UTC "YYYY-MM-DDTHH:II:SSZ") |
limit | integer | Maximum records to return (0-100) |
offset | integer | Number of records to offset the return by |
Update Invoice
Update an existing invoice.
Request Method:
POST
URL Endpoint:
/api/invoice/{ invoice id }
Name | Type | Default | Description | Required |
---|---|---|---|---|
currency | string literal | Currency that invoice amounts should be in ("USD", etc.) | * | |
company_name | string | Name of company issuing the invoice | ||
company_logo_url | string | Hosted location of logo image to include on invoice | ||
customer_number | string | Optional identifier for the invoiced customer to match merchant records | ||
customer_id | string | ID of the saved customer being invoiced (must be a valid customer id if included) | ||
invoice_number | string | Optional identifier for the invoice to match merchant records | ||
payable_to | object | object containing details for the person the invoice is being paid to | * | |
payable_to .id | string | ID of the stored address you want to make the invoice payable to | ||
payable_to .first_name | string | First name | ||
payable_to .last_name | string | Last name | ||
payable_to .company | string | Company name | ||
payable_to .address_line_1 | string | Address line 1 | * | |
payable_to .address_line_2 | string | Address line 2 | ||
payable_to .city | string | City | * | |
payable_to .state | string literal | State, in 2-character format ("KS", "QC", etc.)) | * | |
payable_to .postal_code | string | Postal code (must be a valid postal code for the country provided) | * | |
payable_to .country | string literal | Country, in 2-character format ("US", "CA", "MX", etc.) | * | |
payable_to .phone | string | Phone number | ||
payable_to .fax | string | Fax number | ||
payable_to | string | Email address (must be valid email format, "example@mail.com") | ||
bill_to | object | object containing details for the person the invoice is being billed to | * | |
bill_to .id | string | ID of the stored address you want to make the invoice billable to | ||
bill_to .first_name | string | First name | ||
bill_to .last_name | string | Last name | ||
bill_to .company | string | Company name | ||
bill_to .address_line_1 | string | Address line 1 | * | |
bill_to .address_line_2 | string | Address line 2 | ||
bill_to .city | string | City | * | |
bill_to .state | string literal | State, in 2-character ("KS", "QC", etc.)format | * | |
bill_to .postal_code | string | Postal (must be a valid postal code for the country provided) code | * | |
bill_to .country | string literal | Country, in 2-character ("US", "CA", "MX", etc.) format | * | |
bill_to .phone | string | Phone number | ||
bill_to .fax | string | Fax number | ||
bill_to | string | Email address (must be valid email format, "example@mail.com") | ||
date_due | datetime string | Date the invoice is due ("2021-02-13T06:00:00.000Z")by | * | |
items[#] | object array | array containing line items included in the invoice | * | |
items[#] .status | string literal | "pending" or "paid" | * | |
items[#] .type | string | "" | Type of item | |
items[#] .name | string | "" | Name of item | |
items[#] .description | string | "" | Description of item | |
items[#] .unit_price | integer | Unit price of item | * | |
items[#] .quantity | integer | Quantity of item | * | |
items[#] .quantity_shipped | integer | 0 | Quantity of items shipped to customer | |
items[#] .product_code | string | "" | Product Code of item | |
items[#] .commodity_code | string | "" | Commodity Code of item | |
items[#] .unit_of_measure | string | "" | Unit of measure of item ("lb", "kg", etc.) | |
items[#] .alternate_tax_identifier | string | "" | Alternate tax ID for item | |
items[#] .taxable | boolean | false | Whether local and national tax should be applied at the item level rather than the invoice level | |
items[#] .local_tax_rate | string | "" | Local tax rate for item ("1.000") | |
items[#] .local_tax | integer | 0 | Local tax amount to be added to the item's total, expressed in cents (100 = $1.00) | |
items[#] .national_tax_rate | string | "" | National tax rate for item ("1.000") | |
items[#] .national_tax | integer | 0 | National tax amount to be added to the item's total, expressed in cents (100 = $1.00) | |
items[#] .tax_rate | string | "" | Combined tax rate for item (local tax + national tax) | |
items[#] .tax_amount | integer | 0 | Tax amount to be added to the item's total, expressed in cents (100 = $1.00) | |
items[#] .discount_amount | integer | 0 | Discount to take off the item's total amount, expressed in cents (100 = $1.00)) | |
items[#] .freight_amount | integer | 0 | Freight amount to add to the item's total, expressed in cents (100 = $1.00) | |
advanced_fields | boolean | false | Whether or not to include additional fields for line items (advanced fields include quantity_shipped, freight_amount, unit_of_measure, taxable, local_tax_rate, local_tax, national_tax_rate, national_tax) | |
enable_tax | boolean | false | Whether or not to enable tax (if enabled, tax applied at the invoice level will override taxes applied at the item level) | |
enable_shipping | boolean | false | Whether or not to enable shipping | |
require_shipping_details | boolean | false | Whether or not to require shipping details | |
require_billing_details_on_payment_only | boolean | false | Whether or not to require billing details only at time of payment | |
tax_percent | string | Tax rate to apply to invoice total if enable_tax is true. A rate of "0.000" will cause tax to be read as a flat amount. | * | |
tax | integer | calculated amount | Total tax amount of the invoice, expressed in cents (100 = $1.00). If tax_percent is included and is not "0", this field will be overridden with the calculated amount. | |
shipping | integer | calculated amount | Shipping amount of the invoice, expressed in cents (100 = $1.00) | |
amount_paid | integer | calculated amount | Amount of the invoice that has already been paid, expressed in cents (100 = $1.00) | |
service_fees_paid | integer | calculated amount | Service fee amount that has already been paid, expressed in cents (100 = $1.00) | |
surcharge_paid | integer | calculated amount | Surcharge amount that has already been paid, expressed in cents (100 = $1.00) | |
discount_credited | integer | calculated amount | Discount amount that has already been credited, expressed in cents (100 = $1.00) | |
adjustment | integer | 0 | Apply a payment adjustment to the total amount of the invoice, expressed in cents (100 = $1.00) | |
amount_due | integer | calculated amount | Amount of the invoice that remains due, expressed in cents (100 = $1.00) | |
allow_partial_payment | boolean | false | Whether or not to allow partial payment of the amount due | |
transaction_type | string literal | "sale" | "sale" or "authorize" | |
payment_methods[#] | string array | Allowable payment method types ("card", "ach", and/or "mail") | * | |
card_processor_id (can be "") | string | ID of the payment processor to use for credit card payments | * | |
ach_processor_id (can be "") | string | ID of the payment processor to use for ACH payments | * | |
message | string | Message for customers viewing the invoice | ||
send_via | string literal | How to send invoice notifications ("email", "text", "both", or "none") | * | |
email_to | string | Email address (must be valid email format, "xxxxx@xxxxx.xxx") |
Delete Invoice
Delete the specified invoice.
Request Method:
DELETE
URL Endpoint:
/api/invoice/{ invoice id }
json
{
"status": "success",
"msg": "success"
}
Customer Vault
TIP
This section describes the canonical methods for creating and managing Customer records. The endpoints described in the Customers (Deprecated) section are still available for use, but be advised that using endpoints from both groups in your application simultaneously can result in unintended behaviors.
Create Customer Record
Creates a new Customer record that can contain stored preferences, payment methods, and addresses.
Request Method:
POST
URL Endpoint:
/api/vault/customer
Name | Type | Default | Description | Required |
---|---|---|---|---|
id | string | generated value | Optionally, you may provide a custom id for storing the vaulted customer. Max 40 characters (a-z, A-Z, 0-9) | |
id_format | string literal | Optionally defines a format for the gateway to use when auto-generating an id ("xid_type_last4"). Cannot be used if providing a custom id. | ||
description | string | "" | Text field, max 255 characters | |
flags | string array | [] | Array containing flags for customer settings ("surcharge_exempt") | |
default_payment | object | null | Object containing ach payment method details | |
default_payment .card | object | null | Object containing card payment method details | |
default_payment .card .number | string | "" | Card number | |
default_payment .card .expiration_date | string | "" | Card expiration date ("MMYY" or "MM/YY") | required if default_payment.card is present |
default_payment .ach | object | null | Object containing ach payment method details | |
default_payment .ach .account_number | string | "" | Account number | |
default_payment .ach .routing_number | string | "" | Routing number | |
default_payment .ach .account_type | string literal | Ach account type ("checking" or "savings") | required if default_payment.ach is present | |
default_payment .ach .sec_code | string literal | Ach sec code ("web", "ccd", or "ppd") | required if default_payment.ach is present | |
default_payment .token | string | Payment method token generated by Tokenizer form | ||
default_payment .apple_pay | object | null | Object containing Apple Pay payment method details | |
default_payment .apple_pay .key_id | string | "" | Merchant Apple Pay ID | required if default_payment.apple_pay is present |
default_payment .apple_pay .processor_id | string | "" | Processor ID | |
default_payment .apple_pay .temporary_token | string | "" | Token from WalletJS response | required if using WalletJS |
default_payment .apple_pay .pkpaymenttoken | object | null | PKPaymentToken from Apple Pay JS response | required if using Apple Pay JS |
default_payment .google_pay_token | object or string | null | Object or string containing a Google Pay token | |
default_billing_address | object | null | Object containing billing address details | |
default_billing_address .first_name | string | "" | Addressee first name | |
default_billing_address .last_name | string | "" | Addressee last name | |
default_billing_address .company | string | "" | Company name | |
default_billing_address .line_1 | string | "" | Street address | |
default_billing_address .line_2 | string | "" | Additional delivery details | |
default_billing_address .city | string | "" | City name | |
default_billing_address .state | string | "" | State code ("CA") | |
default_billing_address .postal_code | string | "" | Postal code ("12345") | |
default_billing_address .country | string | "" | Country code ("US") | |
default_billing_address | string | "" | Email address (must be valid email format, "example@mail.com") | |
default_billing_address .phone | string | "" | Phone number ("3216540987") | |
default_billing_address .fax | string | "" | ("3216540987") | |
default_shipping_address | object | null | Object containing shipping address details | |
default_shipping_address .first_name | string | "" | Addressee first name | |
default_shipping_address .last_name | string | "" | Addressee last name | |
default_shipping_address .company | string | "" | Company name | |
default_shipping_address .line_1 | string | "" | Street address | |
default_shipping_address .line_2 | string | "" | Additional delivery details | |
default_shipping_address .city | string | "" | City name | |
default_shipping_address .state | string | "" | State code ("CA") | |
default_shipping_address .postal_code | string | "" | Postal code ("12345") | |
default_shipping_address .country | string | "" | Country code ("US") | |
default_shipping_address | string | "" | Email address (must be valid email format, "example@mail.com") | |
default_shipping_address .phone | string | "" | Phone number ("3216540987") | |
default_shipping_address .fax | string | "" | ("3216540987") |
Get Customer Record By ID
Retrieve details for the specified customer.
Request Method:
GET
URL Endpoint:
/api/vault/{ customer id }
json
{
"status": "success",
"msg": "success",
"data": {
"id": "952f250d-fa85-40ac-a45e-3886f98032c6",
"owner_id": "testmerchant12345678",
"data": {
"customer": {
"addresses": [
{
"city": "Some Town",
"company": "Some Business",
"country": "US",
"email": "user@somesite.com",
"fax": "555555555",
"first_name": "John",
"hash": "cV9qS6UvnnRDJCkgfitHqGrKSRfTARDsLy5zfkNNTcM=",
"id": "bl6nqk69ku6897l45fp0",
"last_name": "Smith",
"line_1": "",
"line_2": "",
"phone": "5555555555",
"postal_code": "60187",
"state": "IL"
}
],
"defaults": {
"billing_address_id": "bl6nqk69ku6897l45fp0",
"payment_method_id": "bl6nqk69ku6897l45fq0",
"payment_method_type": "card",
"shipping_address_id": "bl6nqk69ku6897l45fp0"
},
"description": "test description",
"payments": {
"ach": [],
"cards": [
{
"card_type": "visa",
"expiration_date": "2020-12-31T00:00:00Z",
"id": "bl6nqk69ku6897l45fq0",
"masked_number": "411111******1111"
}
]
}
}
},
"created_at": "2019-08-09T09:04:00.786094073-05:00",
"updated_at": "2019-08-09T09:04:00.786094116-05:00"
}
}
Search Customer Records
Retrieve details for all customer records that match provided search criteria.
Request Method:
POST
URL Endpoint:
/api/vault/customer/search
Name | Type | Default | Description | Required |
---|---|---|---|---|
id | object | Object containing details defining a customer id to match or exclude | ||
id .value | string | "" | Customer record ID to match or exclude | |
id .operator | string | "" | "=" or "!=" | |
address_id | object | Object containing details defining an address id to match or exclude | ||
address_id .value | string | "" | Address ID to match or exclude | |
address_id .operator | string | "" | "=" or "!=" | |
first_name | object | Object containing details defining a customer first name to match or exclude | ||
first_name .value | string | "" | Customer first name to match or exclude | |
first_name .operator | string | "" | "=" or "!=" | |
last_name | object | Object containing details defining a customer last name to match or exclude | ||
last_name .value | string | "" | Customer last name to match or exclude | |
last_name .operator | string | "" | "=" or "!=" | |
company | object | Object containing details defining a company name to match or exclude | ||
company .value | string | "" | Customer company to match or exclude | |
company .operator | string | "" | "=" or "!=" | |
address_line_1 | object | Object containing details defining a street address to match or exclude | ||
address_line_1 .value | string | "" | Customer street address to match or exclude | |
address_line_1 .operator | string | "" | "=" or "!=" | |
address_line_2 | object | Object containing details defining additional address details to match or exclude | ||
address_line_2 .value | string | "" | Customer address details to match or exclude | |
address_line_2 .operator | string | "" | "=" or "!=" | |
city | object | Object containing details defining a city to match or exclude | ||
city .value | string | "" | Customer city to match or exclude | |
city .operator | string | "" | "=" or "!=" | |
state | object | Object containing details defining a state to match or exclude | ||
state .value | string | "" | Customer state to match or exclude | |
state .operator | string | "" | "=" or "!=" | |
postal_code | object | Object containing details defining a postal code to match or exclude | ||
postal_code .value | string | "" | Customer postal code to match or exclude | |
postal_code .operator | string | "" | "=" or "!=" | |
country | object | Object containing details defining a country to match or exclude | ||
country .value | string | "" | Customer country to match or exclude | |
country .operator | string | "" | "=" or "!=" | |
object | Object containing details defining a customer email to match or exclude | |||
email .value | string | "" | Customer email to match or exclude | |
email .operator | string | "" | "=" or "!=" | |
phone | object | Object containing details defining a phone number to match or exclude | ||
phone .value | string | "" | Customer phone to match or exclude | |
phone .operator | string | "" | "=" or "!=" | |
fax | object | Object containing details defining a fax number to match or exclude | ||
fax .value | string | "" | Customer fax to match or exclude | |
fax .operator | string | "" | "=" or "!=" | |
payment_method_type | object | Object containing details defining a payment method type to match or exclude | ||
payment_method_type .value | string | "" | Customer payment method type to match or exclude | |
payment_method_type .operator | string | "" | "=" or "!=" | |
billing_address_id | object | Object containing details defining a billing address id to match or exclude | ||
billing_address_id .value | string | "" | Customer billing address id to match or exclude | |
billing_address_id .operator | string | "" | "=" or "!=" | |
shipping_address_id | object | Object containing details defining a shipping address id to match or exclude | ||
shipping_address_id .value | string | "" | Customer shipping address id to match or exclude | |
shipping_address_id .operator | string | "" | "=" or "!=" | |
created_at | object | Object containing details defining a date range to match | ||
created_at .start_date | string | "" | Beginning of date range | |
created_at .end_date | string | "" | End of date range | |
updated_at | object | Object containing details defining a date range to match | ||
updated_at .start_date | string | "" | Beginning of date range | |
updated_at .end_date | string | "" | End of date range | |
limit | integer | 10 | The number of results to return (1-100) | |
offset | integer | 0 | The number of results to skip (1-1000) |
Update Customer Record
Update an existing customer record.
Request Method:
POST
URL Endpoint:
/api/vault/customer/{ customer id }
Name | Type | Default | Description | Required |
---|---|---|---|---|
description | string | "" | Text field, max 255 characters | |
notes | string | "" | Text field, max 255 characters | |
flags | string array | [] | Array containing flags for customer settings ("surcharge_exempt") | |
defaults | object | null | Object containing id's designating payment methods and addresses to be used as defaults for the customer's transactions | |
defaults .billing_address_id | string | If only one stored address exists on the customer record, that will be used by default | Id of stored address to use as the default billing address for transactions | |
defaults .shipping_address_id | string | If only one stored address exists on the customer record, that will be used by default | Id of stored address to use as the default shipping address for transactions | |
defaults .payment_method_id | string | Id of stored payment method to use as the default payment method for transactions | required if defaults.payment_method_type is present | |
defaults .payment_method_type | string literal | "" | Type of the payment method id supplied ("card" or "ach") | required if defaults.payment_method_id is present |
Delete Customer Record
Delete the specified customer record.
Request Method:
DELETE
URL Endpoint:
/api/vault/{ customer id }
json
{
"status": "success",
"msg": "success"
}
Create Address Record
Create a new address record that will be stored within the customer record. A stored address can be used as the billing and/or shipping address on transactions processed for the customer.
Request Method:
POST
URL Endpoint:
/api/vault/customer/{ customer id }/address
Name | Type | Default | Description | Required |
---|---|---|---|---|
first_name | string | "" | Addressee first name | |
last_name | string | "" | Addressee last name | |
company | string | "" | Company name | |
line_1 | string | "" | Street address | |
line_2 | string | "" | Additional delivery details | |
city | string | "" | City name | |
state | string | "" | State code ("CA") | |
postal_code | string | "" | Postal code ("12345") | |
country | string | "" | Country code ("US") | |
string | "" | Email address (must be valid email format, "example@mail.com") | ||
phone | string | "" | Phone number ("3216540987") | |
fax | string | "" | Fax number ("3216540987") |
Get Address Record By ID
TIP
Address records cannot be fetched individually, please use the Get Customer Record By ID endpoint to retrieve the collection of address records for a specified customer.
Update Address Record
Update an existing address within a customer record.
Request Method:
POST
URL Endpoint:
/api/vault/customer/{ customer id }/address/{ address id }
Name | Type | Default | Description | Required |
---|---|---|---|---|
first_name | string | "" | Addressee first name | |
last_name | string | "" | Addressee last name | |
company | string | "" | Company name | |
line_1 | string | "" | Street address | |
line_2 | string | "" | Additional delivery details | |
city | string | "" | City name | |
state | string | "" | State code ("CA") | |
postal_code | string | "" | Postal code ("12345") | |
country | string | "" | Country code ("US") | |
string | "" | Email address (must be valid email format, "example@mail.com") | ||
phone | string | "" | Phone number ("3216540987") | |
fax | string | "" | Fax number ("3216540987") |
Delete Address Record
Delete the specified address within a customer record.
Request Method:
DELETE
URL Endpoint:
/api/vault/customer/{ customer id }/address/{ address id }
json
{
"status": "success",
"msg": "success"
}
Create Payment Method Record
Create a new stored payment method on the specified customer record. The url endpoint and request body properties vary depending on the type of payment method being created.
Request Method:
POST
Create Card - URL Endpoint:
/api/vault/customer/{ customer id }/card
Create ACH - URL Endpoint:
/api/vault/customer/{ customer id }/ach
Create Card or ACH with Token - URL Endpoint:
/api/vault/customer/{ customer id }/token
Create Card with Apple Pay Token - URL Endpoint:
/api/vault/customer/{ customer id }/applepay
Create Card with Google Pay Token - URL Endpoint:
/api/vault/customer/{ customer id }/googlepay
Name | Type | Default | Description | Required |
---|---|---|---|---|
number | string | "" | Card number | |
expiration_date | string | "" | Card expiration date ("MMYY" or "MM/YY") | * |
Create Payment Method Record Code Samples
json
{
"status": "success",
"msg": "success",
"data": {
"id": "952f250d-fa85-40ac-a45e-3886f98032c6",
"owner_id": "testmerchant12345678",
"data": {
"customer": {
"addresses": [
{
"city": "Some Town",
"company": "Some Business",
"country": "US",
"email": "user@somesite.com",
"fax": "555555555",
"first_name": "John",
"hash": "cV9qS6UvnnRDJCkgfitHqGrKSRfTARDsLy5zfkNNTcM=",
"id": "bl6nqk69ku6897l45fp0",
"last_name": "Smith",
"line_1": "",
"line_2": "",
"phone": "5555555555",
"postal_code": "60187",
"state": "IL"
}
],
"defaults": {
"billing_address_id": "bl6nqk69ku6897l45fp0",
"payment_method_id": "bl6nqk69ku6897l45fq0",
"payment_method_type": "card",
"shipping_address_id": "bl6nqk69ku6897l45fp0"
},
"description": "test description",
"notes": "",
"flags": ["surcharge_exempt"],
"payments": {
"ach": [],
"cards": [
{
"card_type": "visa",
"expiration_date": "2020-12-31T00:00:00Z",
"id": "bl6nqk69ku6897l45fq0",
"masked_number": "411111******1111"
}
]
}
}
},
"created_at": "2019-08-09T09:04:00.786094073-05:00",
"updated_at": "2019-08-09T09:04:00.786094116-05:00"
}
}
Get Payment Method Record By ID
TIP
Payment method records cannot be fetched individually, please use the Get Customer Record By ID endpoint to retrieve the collection of payment method records for a specified customer.
Update Payment Method Record
Update an existing payment method within a customer record.
Request Method:
POST
Update Card - URL Endpoint:
/api/vault/customer/{ customer id }/card/{ payment method id }
Update ACH - URL Endpoint:
/api/vault/customer/{ customer id }/ach/{ payment method id }
Update Token - URL Endpoint:
/api/vault/customer/{ customer id }/token/{ payment method id }
Name | Type | Default | Description | Required |
---|---|---|---|---|
number | string | "" | Card number | |
expiration_date | string | "" | Card expiration date ("MMYY" or "MM/YY") | * |
flags | array | [] | "surcharge_exempt", "applepay", "closed_contact", "contact", "locked_security", "locked_stop_recurring" |
Update Payment Method Record Code Samples
json
{
"status": "success",
"msg": "success",
"data": {
"id": "952f250d-fa85-40ac-a45e-3886f98032c6",
"owner_id": "testmerchant12345678",
"data": {
"customer": {
"addresses": [
{
"city": "Some Town",
"company": "Some Business",
"country": "US",
"email": "user@somesite.com",
"fax": "555555555",
"first_name": "John",
"hash": "cV9qS6UvnnRDJCkgfitHqGrKSRfTARDsLy5zfkNNTcM=",
"id": "bl6nqk69ku6897l45fp0",
"last_name": "Smith",
"line_1": "",
"line_2": "",
"phone": "5555555555",
"postal_code": "60187",
"state": "IL"
}
],
"defaults": {
"billing_address_id": "bl6nqk69ku6897l45fp0",
"payment_method_id": "bl6nqk69ku6897l45fq0",
"payment_method_type": "card",
"shipping_address_id": "bl6nqk69ku6897l45fp0"
},
"description": "test description",
"notes": "",
"flags": ["surcharge_exempt"],
"payments": {
"ach": [],
"cards": [
{
"card_type": "visa",
"expiration_date": "2020-12-31T00:00:00Z",
"id": "bl6nqk69ku6897l45fq0",
"masked_number": "411111******1111"
}
]
}
}
},
"created_at": "2019-08-09T09:04:00.786094073-05:00",
"updated_at": "2019-08-09T09:04:00.786094116-05:00"
}
}
Delete Payment Method Record
Delete the specified payment method within a customer record.
Request Method:
DELETE
Delete Card - URL Endpoint:
/api/vault/customer/{ customer id }/card/{ card id }
Delete ACH - URL Endpoint:
/api/vault/customer/{ customer id }/ach/{ ach id }
json
{
"status": "success",
"msg": "success"
}