Create a Charge - Keyed

post

https://testapi.payarc.net/v1/charges

This endpoint enables you to securely initiate payment transactions by submitting charge details via a POST request.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

amount

int32

required

A positive integer in cents representing how much to charge. Example: 9 would be $0.09; 99999999 would be $999,999.99. In the sandbox environtment the minimum amount allowed is $0.50 USD.

currency

string

required

Three-letter ISO currency code, in lowercase. Currency must be 'usd'

customer_id

string

The unique alphanumeric identifier for a customer. A transaction is associated with a customer when a customer ID is included in the sale request. IMPORTANT: Customer_id is accepted when none of the following values are present in the request: token_id, card_number.

card_id

string

The unique alphanumeric identifier for a card.

statement_description

string

length ≤ 25

An arbitrary string to be displayed on your customer’s credit card statement.

token_id

string

An alphanumeric that represents a credit card or a debit card. This is obtained by using the 'Create a Token' API. IMPORTANT: token_id is accepted when none of the following are present in the request: customer_id, card_number.

capture

int32

Defaults to 1

Boolean option to capture charge immediately or pre-authorize and capture at a later date. 1 represents that the charge has to be captured immediately. 0 represents the charge issues an authorization (or pre-authorization) and will need to be captured later. Uncaptured charges expire in seven days.

card_level

string

enum

Defaults to LEVEL1

Indicates the extent of information to be provided for a transaction. IMPORTANT: If card_level is not specified, then PAYARC will process the transaction as LEVEL1.

Allowed:

sales_tax

int32

Sales tax amount represented in cents. Examples: 9 would be $0.09; 999999999999 would be $9,999,999,999.99. Note: Applicable for LEVEL2 or LEVEL3 transactions. If the transaction is tax-exempt, then enter 0 for the value.

terminal_id

string

The alphanumeric terminal ID from which the transaction was made.

tip_amount

int32

The tip amount of the transaction. Example: 9 would be $0.09; 999999999999 would be $9,999,999,999.99

purchase_order

string

length between 0 and 25

The value used by the customer to identify an order. Issued by the buyer to the seller. Applicable for LEVEL2 or LEVEL3 transactions.

order_date

string

The date the order was processed. Format: YYYY-MM-DD. Applicable for LEVEL2 for AMEX transactions and all LEVEL3 transactions.

customer_ref_id

string

length between 0 and 17

The reference identifier supplied by the commercial cardholder. Alphanumeric and Whitespace. Applicable for LEVEL2 for AMEX transactions and all LEVEL3 transactions.

ship_to_zip

int32

The postal code for the address to which the goods are being shipped. Alphanumeric. Applicable for LEVEL2 for AMEX transactions and all LEVEL3 transactions.

amex_descriptor

string

length between 5 and 40

The value of the Transaction Advice Addendum field that displays descriptive information about a transaction on a customer's AMEX card statement. Alphanumeric and Whitespace. IMPORTANT: Applicable for LEVEL2 transactions for AMEX only.

supplier_reference_number

string

length between 0 and 9

This field contains a reference number that is used by AMEX to obtain supporting information on a transaction from a supplier. Alphanumeric and Whitespace. Applicable for LEVEL2 for AMEX transactions and all LEVEL3 transactions.

tax_amount

int32

The tax amount. Example: 9 would be $0.99; 999999999999 would be $9,999,999,999.99. Applicable for all LEVEL3 transactions. If tax amount is $0.00, enter 0 as the value.

tax_category

string

enum

The type of tax.

Allowed:

customer_vat_number

string

length between 0 and 13

Government-assigned tax identification number of the merchant. Indicates the customer's government-assigned tax identification number or the identification number assigned to their purchasing company by the tax authorities. Applicable for LEVEL3 transactions.

summary_commodity_code

string

length between 0 and 4

The international description code of the overall goods or services being supplied. Alphanumeric and Whitespace. Applicable for LEVEL3 transactions. Merchants can request an updated listing of the currently defined codes.

shipping_charges

int32

The dollar amount for shipping or freight charges applied to a product or transaction. Example: 9 would be $0.09; '9999' would be '$99.99'Applicable for LEVEL3 transactions. If shipping costs are '$0.00' enter '0' as the value.

duty_charges

int32

Indicates the total charges for any import or export duties included in the order. Examples: 9 would be $0.09; 999999999999 would be $9,999,999,999.99. Applicable for LEVEL3 transactions.

ship_from_zip

int32

The postal code for the address from which the goods were shipped. Alphanumeric. Applicable for LEVEL3 transactions.

destination_country_code

string

length between 1 and 4

The destination country code indicator. Alphanumeric. Applicable for LEVEL3 transactions.

tax_type

string

length between 0 and 50

The type of tax. Alphanumeric. Applicable for LEVEL3 transactions.

vat_invoice

string

The Value Added Tax (VAT) invoice number associated with the transaction.Min Lengthtext-Max Lengthtext-NotesAlphanumeric and Whitespace0 characters15 charactersApplicable for LEVEL3 transactions.

tax_rate

int32

The type of tax rate. This field is used if tax_category is not used. The default sales tax rate in percentage must be between 0.1% - 22%. Applicable for LEVEL3 transactions.

string

length between 5 and 40

The cardholder’s email address. Alphanumeric and Special Characters

cvv

int32

The three or four-digit security code on the card. IMPORTANT: Required when customer_id is passed and the card is not authorized/verified. Refer to the Create a Token API to authorize a card.

phone_number

int32

The cardholder’s phone number.

surcharge

int32

A positive number representing the surcharge percentage to be added for the charge.

avs_parameters

int32

enum

AVS transaction parameters that provide post-authorization instructions. Mapping: 1 = If AVS ZIP matches but AVS Street Fails, then block the transaction.2 = If AVS ZIP matches but AVS Street Fails, then pass the transaction. 3 = If AVS ZIP fails but AVS Street matches, then block the transaction. 4 = If AVS ZIP fails but AVS Street matches, then pass the transaction. 5 = If AVS ZIP fails and AVS Street fails, then block the transaction. 6 = If AVS ZIP fails and AVS Street fails, then pass the transaction.

Allowed:

bin_location_parameters

int32

BIN location transaction parameters that provide post-authorization instructions. Mapping: 1 = If BIN is not equal to USA, then void. 2 If BIN is not equal to USA and Canada, then void.

bin_card_type_parameters

int32

BIN card type transaction parameters that provide post-authorization instructions. Mapping: 1 = If BIN is a credit card then void. 2= If BIN is a debit card then void. 3 = If BIN is a prepaid card then void. 4 = If BIN is a prepaid and/or debit card then void.

metadata

string

Metadata is useful for storing additional, structured information on an object. You can specify up to 50 keys, with key names up to 20 characters long and values up to 100 characters long.

do_not_send_email_to_customer

string

enum

Defaults to yes

To prevent sending an email to the customer for a transaction. By default, the system will send an email.

Allowed:

do_not_send_sms_to_customer

string

enum

To prevent sending an SMS to the customer.

Allowed:

card_number

string

The 14-19 digit card number used for the transaction. IMPORTANT: The field is accepted when none of the following are present in the request. customer_id, token_id.

exp_month

string

The month value, MM displayed on the card used for the transaction. IMPORTANT: The field is accepted when none of the following are present in the request: customer_id, token_id.

exp_year

int32

The YYYY value mentioned on the card used for the transaction. IMPORTANT: The field is accepted when none of the following are present in the request. customer_id, token_id.

card_holder_name

string

Name of the cardholder as mentioned on the card used to carry out a transaction. IMPORTANT: The field is accepted when none of the following are present in the request. customer_id, token_id.

address_line1

string

length between 1 and 200

The cardholder's billing address for line 1. Alphanumeric and Whitespace. IMPORTANT: The field is accepted when none of the following are present in the request. customer_id, token_id. Payfac Max Length: 30 characters.

address_line2

string

length between 1 and 200

The cardholder's billing address for line 2. Alphanumeric and Whitespace. IMPORTANT: The field is accepted when none of the following are present in the request. customer_id, token_id. Payfac Max Length: 30 characters.

city

string

length ≤ 30

The cardholder's city name. Can be a City/District/Suburb/Town/Village. IMPORTANT:The field is accepted when none of the following are present in the request. customer_id, token_id.

state

string

length between 1 and 50

The cardholder's state name. Can be State/County/Province/Region. IMPORTANT: The field is accepted when none of the following are present in the request. customer_id, token_id.

zip

int32

The cardholder's billing ZIP code. IMPORTANT: The field is accepted when none of the following are present in the request. customer_id, token_id.

country

string

The cardholder's country name. IMPORTANT: The field is accepted when none of the following are present in the request. customer_id, token_id.

splits

array of objects

Optional array of split instructions for distributing the payment.

splits

product_details

array of objects

product_details

Headers

string

required

Defaults to application/json

Indicates which content types, expressed as MIME types, the client is able to understand.

Content-Type

string

required

Defaults to application/json

Indicates the media type of the resource sent in the HTTP message body. r /r /Possible Values:/br / application/jsonr /application/x-www-form-urlencoded

Idempotency-Key

string

Ensures that a request is processed only once, even if it is retried due to network timeouts or errors. When provided, the server uses the key to identify and return the result of a previous request with the same key, preventing duplicate operations (e.g., duplicate payments or record creation).

Responses

201201

422422