Charge

Process a payment charge with card details and additional transaction information. > **Disclaimer:** This documentation combines requirements from all compatible payment gateways. Not all fields or requirements may apply to your specific integration. For questions about your setup, contact [integrations@runpayments.io](mailto:integrations@runpayments.io). **Cybersource Gateway:** The following additional fields are required when processing through Cybersource: `name`, `address2`, `region`, `country`, `phone`, `email`.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.
account_tokenstringRequired
Tokenized payment account number. Generated from Runner.js or Run Merchant dev tools.
midstringRequired
Merchant ID
amountintegerRequired

Ticket amount (in cents)

expirationstringRequired
Card expiration
account_zipstringRequired
Cardholder zip code
cvnstringRequired

Cardholder CVN (CVV2, CID, CAV2, CVC2)

currencystringRequired

Three character currency indicator (Defaults to USD)

address1stringRequired
Account holder's street address
citystringRequired
Account holder's city
cofstringOptional
Returns cof value if included in auth request.
user_identifierstringOptional
The user that initiated the activity.
cof_permstringOptional

Permission granted to save card on file for a specific profile (Y or N)

terminal_idstringOptional
The terminal ID as identified in the auth request.
cof_schedstringOptional

Required for transactions using stored cardholder payment information. For a merchant-initiated transaction (MIT), the cof_sched parameter specifies whether the transaction is a one-time payment or a scheduled recurring payment.

card_binstringOptional
Return BIN lookup fields in response
customerstringOptional
Customer ID
capturestringOptional

Capture upon approval (Y or N)

namestringOptional
Account holder's name
company_namestringOptional
Account holder's company name
address2stringOptional
Account holder's street address line 2
regionstringOptional
Account holder's region, US State, Mexican State, or Canadian Province
countrystringOptional

Account holder’s country (2-character country code)

phonestringOptional
Account holder's phone number
emailstringOptional
Account holder's email address
com_indenumOptional

CNP transaction origin. Optional, but strongly encouraged, as this field is used to ensure a transaction qualifies at the correct interchange level. Valid values: R (recurring), T (telephone), E (ecomm or mobile app).

Allowed values:
order_idstringOptional
Unique source system order number, if left blank it will be generated for you
invoice_idstringOptional

User-defined invoice identifier.

auth_codestringOptional
Authorization Code
vaultstringOptional

Indicates if the payment account should be saved in the vault (Y or N)

po_numberstringOptional
Customer purchase order number
tax_amountstringOptional
Tax amount for the order, either decimal or in currency minor units. If taxexempt is Y, then 0.
freight_amountstringOptional
Total order freight amount, default 0
duty_amountstringOptional
Total order duty amount, default 0
order_datestringOptional
YYYYMMDD format. For most industries this is the delivery date for the order.
shipping_zipstringOptional
If country is US, must be 5 or 9 digits. Otherwise, any alphanumeric string is accepted
origin_zipstringOptional
Same as above
shipping_countrystringOptional

Ship to country code - Defaults to US

line_itemslist of anyOptional
Level 3 Processing Line Items
vault_idintegerOptional
The id for the vault card
vault_holder_idstringOptional

This is the vault customer ID that is returned once a vault is created. When included in the request, it will store the vault account with the specified vault holder. See the Vaults guide for more information.

custom_01stringOptional

Transaction-level custom field. custom_01 through custom_05 are available for use at the transaction level. See Custom Fields for more information.

custom_06stringOptional

Account-level custom field. custom_06 through custom_10 are available for use at the account level. See Custom Fields for more information.

Response

Charge processed successfully
trans_idstring
Reference number for the transaction
vault_idinteger
The id for the vault card
vault_holder_idstring
The vault customer ID
resultenum

Result of auth request. A = Approved, B = Retry, C = Declined.

Allowed values:
account_tokenstring
Tokenized payment account number.
resp_codestring
Response code that represents description of the response.
resp_textstring
Text description of response
resp_procstring
Abbreviation that represents platform and processor for transaction
cofstring
Returns cof value if included in auth request
avs_respstring
AVS verification response code
cvv_respstring
CVV response code
bin_infostring
Array that returns fields from BIN response
bin_typestring
Type of BIN
pos_entrystring
POS Entry Mode
fee_amountinteger

A fee amount (e.g. a credit card surcharge amount) applied to the transaction, in dollars and cents.

fee_authcodestring
Duplicate of authcode field if the transaction included a fee
fee_formatstring
Fee format configured for merchant account.
fee_midstring
MID used for processing the fee. If not applicable, returns an empty value.
fee_txnstring
Unique reference number used for processing fee. If not applicable, returns an empty value
fee_typestring
Type of fee applied to transaction
fee_valuestring

Fee rate applied to the transaction (in basis points)

decline_categorystring
Visa decline category
decline_category_textstring
Visa decline category description
authcodestring
Authcode from issuer
comm_cardstring

Commercial card flag - Y if corporate or purchase card

emvstring

Cryptogram (ARPC) only returned when emv data is present

emv_tag_datastring

Receipt/EMV tag data

user_identifierstring
The user that initiated the activity
midstring
Merchant ID
amountinteger
Ticket amount
expirationstring
Card expiration
account_zipstring
Cardholder zip
address1string
Account holder's street address
citystring
Account holder's city
regionstring
Account holder's region, US State, Mexican State, Canadian Province
order_idstring
Source system order number
card_numberstring

Masked primary account number (PAN)

batch_idstring
Automatically created and assigned unless otherwise specified
vaultstring

Indicates if the payment account was saved in the vault (Y or N)

card_typestring
Visa, MC, Discover, Amex, etc.
currencystring
Three character currency indicator
company_namestring
Account holder's company name
address2string
Account holder's street address line 2
countrystring

Account holder’s country - 2-character country code

phonestring
Account holder's phone
emailstring
Account holder's email
auth_codestring
Authorization code from issuer

Errors