---
title: "Create a Charge - Keyed"
method: POST
path: "/v1/charges"
---

# Create a Charge - Keyed

`POST /v1/charges`

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

## Headers

- `Accept` string, required
- `Content-Type` string, required
- `Idempotency-Key` string

## Request body

- object
  - `amount` integer, 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 — 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` integer — 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` 'LEVEL2' | 'LEVEL3' — 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.
  - `sales_tax` integer — 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` integer — The tip amount of the transaction. Example: 9 would be $0.09; 999999999999 would be $9,999,999,999.99
  - `purchase_order` string — 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 — The reference identifier supplied by the commercial cardholder. Alphanumeric and Whitespace. Applicable for LEVEL2 for AMEX transactions and all LEVEL3 transactions.
  - `ship_to_zip` integer — 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 — 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 — 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` integer — 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` 'SERVICE' | 'DUTY' | 'VAT' | 'ALTERNATE' | 'NATIONAL' | 'TAX_EXEMPT' — The type of tax.
  - `customer_vat_number` string — 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 — 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` integer — 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` integer — 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` integer — The postal code for the address from which the goods were shipped. Alphanumeric. Applicable for LEVEL3 transactions.
  - `destination_country_code` string — The destination country code indicator. Alphanumeric. Applicable for LEVEL3 transactions.
  - `tax_type` string — 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` integer — 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.
  - `email` string — The cardholder’s email address. Alphanumeric and Special Characters
  - `cvv` integer — 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` integer — The cardholder’s phone number.
  - `surcharge` integer — A positive number representing the surcharge percentage to be added for the charge.
  - `avs_parameters` integer — 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.
  - `bin_location_parameters` integer — 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` integer — 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` 'yes' | 'no' — To prevent sending an email to the customer for a transaction. By default, the system will send an email.
  - `do_not_send_sms_to_customer` 'yes' | 'no' — To prevent sending an SMS to the customer.
  - `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` integer — 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 — 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 — 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 — 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 — 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` integer — 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` object[] — Optional array of split instructions for distributing the payment.
    - `mid` string, required — Merchant ID to receive this portion of the split.
    - `amount` integer — Fixed amount to split (optional if percent is used).
    - `percent` string, required — Percentage of the total amount to allocate.
  - `product_details` object[]
    - `product_code` string
    - `product_name` string
    - `price` integer
    - `quantity` integer
    - `product_discount_details` object[]
      - `product_discount_name` string
      - `product_discount_amount` string
      - `product_discount_percentage` string
      - `product_discount_type` string
    - `product_tax_details` object[]
      - `product_tax_name` string
      - `product_tax_amount` string
      - `product_tax_percentage` string
      - `product_tax_type` string
    - `product_commodity_code` string
  - `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` '2' | '3' | '4' | '5' | '6' | '7' | '8' | 'A' | 'R' | 'T' — The ECI indicates the security level of the payment information provided to the merchant. <table> <tr><td>2</td><td>Recurring Mail/Telephone Order Transaction.</td></tr> <tr><td>3</td><td>Installment Payment of a Mail/Telephone Order Transaction.</td></tr> <tr><td>4</td><td>Unknown Classification/Other mail order.</td></tr> <tr><td>5</td><td>Secure electronic commerce transaction.</td></tr> <tr><td>6</td><td>Non-Authenticated Electronic Commerce Transaction.</td></tr> <tr><td>7</td><td>Channel Encrypted Transaction.</td></tr> <tr><td>8</td><td>Non-secure Transaction.</td></tr> <tr><td>A</td><td>In-App Authentication (only for Mastercard, AMEX and Discover).</td></tr> <tr><td>R</td><td>First recurring SecureCode Phone Order transaction (Mastercard Only)</td></tr> <tr><td>T</td><td>Single nonrecurring SecureCode Phone Order transaction (Mastercard Only)</td></tr> </tr></table>
  - `ucaf_collection_indicator` '0' | '1' | '2' | '5' | '6' | '7' — Universal Cardholder Authentication Field. Indicates the status of the AAV submitted with the transaction request. <table> <tr><td>0</td><td>UCAF data is not supported by the merchant or the merchant has chosen not to send the indicator.</td></tr> <tr><td>1</td><td>UCAF data collection is supported by the merchant and UCAF data was present and contained an attempted AAV for MasterCard SecureCard.</td></tr> <tr><td>2</td><td>UCAF data collection is supported by the merchant and UCAF data was present and contained a fully authenticated AAV.</td></tr> <tr><td>5</td><td>Issuer Risk-Based Decisioning.</td></tr> <tr><td>6</td><td>Merchant Risk-Based Decisioning.</td></tr> <tr><td>7</td><td>Partial Shipment and recurring payment. Liability will depend on the original UCAF values provided and matching with the initial transaction.</td></tr> </table>
  - `security_protocol` '21' | '24' — The cardholder authentication method used for secure Mastercard transactions. Security protocol + UCAF is Electronic security level indicator. <table> <tr><td>21</td><td>Channel encryption; cardholder certificate not used.</td></tr> <tr><td>24</td><td>Tokenized Payment</td></tr> </table>
  - `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` '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' — Program Protocol / Cardholder Authentication Field. Mastercard SecureCode transactions only. <table> <tr><td>1</td><td>EMV 3-D Secure Version 2.1</td></tr> <tr><td>2</td><td>EMV 3-D Secure Version 2.2</td></tr> <tr><td>3</td><td>EMV 3-D Secure Version 2.3</td></tr> <tr><td>4</td><td>EMV 3-D Secure Version 2.4</td></tr> <tr><td>5</td><td>EMV 3-D Secure Version 2.5</td></tr> <tr><td>6</td><td>EMV 3-D Secure Version 2.6</td></tr> <tr><td>7</td><td>EMV 3-D Secure Version 2.7</td></tr> <tr><td>8</td><td>EMV 3-D Secure Version 2.8</td></tr> <tr><td>9</td><td>EMV 3-D Secure Version 2.9</td></tr> </table>

## Response `201`

201

- union
  - object
    - `data` object
      - `object` string
      - `id` string
      - `amount` integer
      - `amount_refunded` integer
      - `amount_captured` string
      - `amount_voided` integer
      - `application_fee_amount` integer
      - `tip_amount` integer
      - `payarc_fees` integer
      - `type` string
      - `net_amount` integer
      - `captured` integer
      - `is_refunded` integer
      - `status` string
      - `auth_code` string
      - `failure_code` unknown
      - `failure_message` unknown
      - `charge_description` unknown
      - `statement_description` string
      - `invoice` unknown
      - `under_review` boolean
      - `created_at` integer
      - `updated_at` integer
      - `email` string
      - `phone_number` string
      - `card_level` string
      - `sales_tax` unknown
      - `purchase_order` unknown
      - `supplier_reference_number` unknown
      - `customer_ref_id` unknown
      - `ship_to_zip` unknown
      - `amex_descriptor` unknown
      - `customer_vat_number` unknown
      - `summary_commodity_code` unknown
      - `shipping_charges` unknown
      - `duty_charges` unknown
      - `ship_from_zip` unknown
      - `destination_country_code` unknown
      - `vat_invoice` unknown
      - `order_date` unknown
      - `tax_category` unknown
      - `tax_type` unknown
      - `tax_rate` unknown
      - `tax_amount` unknown
      - `created_by` string
      - `terminal_register` unknown
      - `tip_amount_refunded` unknown
      - `sales_tax_refunded` unknown
      - `shipping_charges_refunded` unknown
      - `duty_charges_refunded` unknown
      - `pax_reference_number` unknown
      - `refund_reason` unknown
      - `refund_description` unknown
      - `surcharge` integer
      - `toll_amount` unknown
      - `refund` object
        - `data` unknown[]
          - unknown
      - `card` object
        - `data` object
          - `object` string
          - `id` string
          - `address1` string
          - `address2` string
          - `card_source` string
          - `card_holder_name` string
          - `is_default` integer
          - `exp_month` string
          - `exp_year` string
          - `is_verified` integer
          - `fingerprint` string
          - `city` unknown
          - `state` unknown
          - `zip` string
          - `brand` string
          - `last4digit` string
          - `first6digit` integer
          - `country` unknown
          - `avs_status` unknown
          - `cvc_status` unknown
          - `address_check_passed` integer
          - `zip_check_passed` integer
          - `customer_id` string
          - `created_at` integer
          - `updated_at` integer
    - `meta` object
      - `include` string[]
      - `custom` unknown[]
        - unknown
  - object
    - `data` object
      - `object` string
      - `id` string
      - `amount` integer
      - `amount_refunded` integer
      - `amount_captured` string
      - `amount_voided` integer
      - `application_fee_amount` integer
      - `tip_amount` integer
      - `payarc_fees` integer
      - `type` string
      - `net_amount` integer
      - `captured` integer
      - `is_refunded` integer
      - `status` string
      - `auth_code` string
      - `failure_code` unknown
      - `failure_message` unknown
      - `charge_description` unknown
      - `statement_description` string
      - `invoice` unknown
      - `under_review` boolean
      - `created_at` integer
      - `updated_at` integer
      - `email` string
      - `phone_number` string
      - `card_level` string
      - `sales_tax` unknown
      - `purchase_order` unknown
      - `supplier_reference_number` unknown
      - `customer_ref_id` unknown
      - `ship_to_zip` unknown
      - `amex_descriptor` unknown
      - `customer_vat_number` unknown
      - `summary_commodity_code` unknown
      - `shipping_charges` unknown
      - `duty_charges` unknown
      - `ship_from_zip` unknown
      - `destination_country_code` unknown
      - `vat_invoice` unknown
      - `order_date` unknown
      - `tax_category` unknown
      - `tax_type` unknown
      - `tax_rate` unknown
      - `tax_amount` unknown
      - `created_by` string
      - `terminal_register` unknown
      - `tip_amount_refunded` unknown
      - `sales_tax_refunded` unknown
      - `shipping_charges_refunded` unknown
      - `duty_charges_refunded` unknown
      - `pax_reference_number` unknown
      - `refund_reason` unknown
      - `refund_description` unknown
      - `refund` object
        - `data` unknown[]
          - unknown
      - `card` object
        - `data` object
          - `object` string
          - `id` string
          - `address1` unknown
          - `address2` unknown
          - `card_source` string
          - `card_holder_name` unknown
          - `is_default` integer
          - `exp_month` string
          - `exp_year` string
          - `is_verified` integer
          - `fingerprint` string
          - `city` unknown
          - `state` unknown
          - `zip` unknown
          - `brand` string
          - `last4digit` string
          - `first6digit` integer
          - `country` unknown
          - `avs_status` unknown
          - `cvc_status` unknown
          - `address_check_passed` integer
          - `zip_check_passed` integer
          - `customer_id` unknown
          - `created_at` integer
          - `updated_at` integer
    - `meta` object
      - `include` string[]
      - `custom` unknown[]
        - unknown

## Other responses

- `422` — 422

---

[API](https://skmtc.net/payarc/apis/payarc-sandbox.md) · [All operations](https://skmtc.net/payarc/apis/payarc-sandbox/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/payarc/payarc-sandbox/versions/face82bdd778/schema)