v1

latestOpenAPI 3.0.12026-07-242871595.3 MB
ORDERS

Pay for an order

Pays for a specific order with a payment source. Important: Either a payment source or customer must be associated with an order for payment. If a customer is not attached to the order, then the source in this field is charged for the order.

post/v1/orders/{orderId}/pay

Path parameters

orderIdstring required

Universally unique identifier (UUID) of the order.

Headers

User-Agentstring required

Identifies the application, operating system, vendor, and/or version of the requesting user agent. Format: <AppName>/<Version> <Comment>

x-forwarded-forstring required

Client internet protocol (IP) address of the web browser from which the customer’s payment originates. Note: Header x-forwarded-for is required for enhanced security and accuracy of Clover services. Requests that don’t include the header are not successful.

Request body

customerstring required

Universally unique identifier (UUID) of the customer being charged for the order. The customer indicated here is charged instead of the customer associated with the order creation. See Create a customer. Important: Either a payment source or customer must be associated with an order for payment. If a customer is not attached to the order, then the source in this field is charged for the order.

ecomind'ecom' | 'moto'

Indicates who entered the card data used for a charge - customer (ecom) or merchant (moto).

emailstring

Email address of the customer placing the order. Required if the email address is not provided when creating the order.

amountinteger

Charge amount. If the charge request includes tax (tax_rate_uuid or tax_amount), this value must be the sum of any item prices and any tax or tip. For example: If the item cost = $10 and the tax is $1, the amount is 1100 cents ($11). Format: Cents

currencystring

Three-letter ISO 4217 currency code. Format: Lower case Length: Maximum 3

partial_redemptionboolean

Indicates whether the charge can be authorized for a lesser amount. Values: True False - Default

expandstring[]

Additional information provided as an expanded response, for example, related objects nested within the parent. See Use expandable fields.

external_reference_idstring

Unique identifier (ID), such as an invoice or purchase order (PO) number, that is sent to the merchant's gateway and displayed in settlement records. Format: Supported for US—alphanumeric characters with in-between spaces. Length: Maximum 12, including spaces and alphanumeric characters.

external_customer_referencestring

Customer reference number from the merchant's order management system.

metadataobject

Set of key-value pairs that you can attach to the object. This parameter is useful for storing additional information about the object in a structured format. Length: Maximum 500 characters

sourcestring

Payment source to charge, such as token or alternate_tender. See Create a card token. or Create an ACH token. Important: Either a payment source or customer must be associated with an order for payment. If a customer is not attached to the order, then the source in this field is charged for the order.

intent'save_credential_on_file'

Intent of the external token. Note: For a new TransArmor<sup>®</sup> token, select save_credential_on_file.

tip_amountinteger

Amount paid in tips. This value is automatically added to the total amount when the transaction is finalized.

Response

Successful response. Order payment successfully processed.

amountinteger required

Total order amount in the smallest monetary unit of the merchant's currency.

amount_paidinteger

Amount currently paid toward the order total.

amount_dueinteger

Amount still due toward the order total.

tax_amountinteger

Merchant-defined flat tax amount for the order. Format: Cents

tax_amount_paidinteger

Amount currently paid toward the tax total.

tip_amountinteger

Amount paid in tips. This value is automatically added to the total amount when the transaction is finalized.

partial_authboolean

Indicates if partial approval has occurred.

amount_returnedinteger nullable
chargestring

Charge identifier. Returns the result when the order status is paid, fulfilled, or refunded.

auth_codestring nullable

Authorization code of the charge, if available.

external_coupon_codestring

External coupon code available for this order.

upstream_idstring

Billing address country, if provided.

updatedinteger

Time stamps when the order was last updated.

first6string

First 6 numbers of the primary account number.

amount_preauthorizedinteger

Displays the pre-authorized amount for the order. If any.

ref_numstring nullable

If available, the reference number returned from the payment gateway if the transaction is successful.

warning_messagestring nullable

Detailed warning information about the order or associated charge (for example, missing original transaction id for c-token).

ecomind'ecom' | 'moto' | 'retail'

Indicates who entered the card data used for a charge - customer (ecom) or merchant (moto).

createdinteger required

Displays results based on the object's created field. Values: String with a Unix timestamp (in milliseconds) or Dictionary of multiple options describing a time range.

currencystring required

Three-letter ISO 4217 currency code.

customerstring

Customer identifier.

emailstring nullable

Email address of the customer placing the order.

external_reference_idstring

An identifier such as an invoice or PO number, passed to the merchant's gateway and ultimately appears in settlement records. Note: Applicable for US customers, spaces are allowed in the reference number. Length: Max 12 (including alphanumeric characters)

external_customer_referencestring

Customer reference number from the merchant's order management system.

idstring required

Order identifier.

livemodeboolean required

Indicates whether the item is in production or sandbox. True - Item is in production False - Item is in sandbox

metadataobject required

Set of key-value pairs that you can attach to the object. This parameter is useful for storing additional information about the object in a structured format. Length: Maximum 500 characters

object'order' required

Object type. Objects with the same type have the same value.

selected_shipping_methodstring nullable

Selected shipping method of the order. If present, the value is set from the shipping_methods list. For multiple shipping methods, the first method is automatically selected.

status'created' | 'paid' | 'canceled' | 'fulfilled' | 'returned' | 'partially_paid' | 'partially_refunded' | 'refunded' required

Current order status.