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…

These resources support advanced transaction features and integration troubleshooting:

Metatdata

To request transaction metadata, append the include query parameter to your request:
/v1/charges?include=transaction_metadata

LEVEL 2 or LEVEL 3 Card Data

When creating a new charge, you have the option to provide additional card data at LEVEL2 or LEVEL3. These enhanced data levels can provide benefits such as lower Visa and Mastercard interchange rates, particularly for commercial, corporate, purchasing, business, or government cards.

The following fields are required to process a transaction with card_level set to LEVEL2:

address\_line1
purchase\_order
sales\_tax
zip

To process transactions with card_level set to LEVEL3, you must include the fields required for LEVEL 2, along with the following additional fields:

customer\_vat\_number
destination\_country\_code
duty\_charges
order\_date
ship\_from\_zip
ship\_to\_zip
shipping\_charges
summary\_commodity\_code
tax\_amount
tax\_category
tax\_rate
tax\_type
vat\_invoice
product\_details

Instructional Funding (Splits)

Merchants configured with instructional funding are required to include the splits array in the request payload.

At least one valid split instruction must be provided — otherwise, the request may result in errors and could delay funding of the transaction.

API Troubleshooting

When creating a new charge, you may encounter the following error codes. Each status is associated with a specific error message. You can find a detailed error message breakdown in our Charges FAQ.

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

secure_code

string

The 3D Secure Code, automatically generated by the merchant's software.
Note: This alphanumeric field must use uppercase letters otherwise it will result in a re-enter error.

eci_indicator

string

enum

The ECI indicates the security level of the payment information provided to the merchant.

2	Recurring Mail/Telephone Order Transaction.
3	Installment Payment of a Mail/Telephone Order Transaction.
4	Unknown Classification/Other mail order.
5	Secure electronic commerce transaction.
6	Non-Authenticated Electronic Commerce Transaction.
7	Channel Encrypted Transaction.
8	Non-secure Transaction.
A	In-App Authentication (only for Mastercard, AMEX and Discover).
R	First recurring SecureCode Phone Order transaction (Mastercard Only)
T	Single nonrecurring SecureCode Phone Order transaction (Mastercard Only)

ucaf_collection_indicator

string

enum

Universal Cardholder Authentication Field. Indicates the status of the AAV submitted with the transaction request.

0	UCAF data is not supported by the merchant or the merchant has chosen not to send the indicator.
1	UCAF data collection is supported by the merchant and UCAF data was present and contained an attempted AAV for MasterCard SecureCard.
2	UCAF data collection is supported by the merchant and UCAF data was present and contained a fully authenticated AAV.
5	Issuer Risk-Based Decisioning.
6	Merchant Risk-Based Decisioning.
7	Partial Shipment and recurring payment. Liability will depend on the original UCAF values provided and matching with the initial transaction.

Allowed:

security_protocol

string

enum

The cardholder authentication method used for secure Mastercard transactions. Security protocol + UCAF is Electronic security level indicator.

21	Channel encryption; cardholder certificate not used.
24	Tokenized Payment

Allowed:

directory_server_transaction_id

string

Transaction ID generated by the EMV 3DS Mastercard Directory Server- Applicable to Mastercard SecureCode transactions only. Allowed characters: a-z A-Z 0-9 Space @ # % ( ) / .(Dot) ' : $ , / _ -

program_protocol

string

enum

Program Protocol / Cardholder Authentication Field. Mastercard SecureCode transactions only.

1	EMV 3-D Secure Version 2.1
2	EMV 3-D Secure Version 2.2
3	EMV 3-D Secure Version 2.3
4	EMV 3-D Secure Version 2.4
5	EMV 3-D Secure Version 2.5
6	EMV 3-D Secure Version 2.6
7	EMV 3-D Secure Version 2.7
8	EMV 3-D Secure Version 2.8
9	EMV 3-D Secure Version 2.9

Headers

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).

content-type

string

enum

Defaults to application/json

Generated from available request content types

Allowed:

Responses

201201

422422