CyberSource orders API
An order is a service that is used for initiating a transaction with itemized details, shipping, billing and buyer information.
OpenAPI Specification
swagger: '2.0'
info:
description: All CyberSource API specs merged together. These are available at https://developer.cybersource.com/api/reference/api-reference.html
version: 0.0.1
title: CyberSource Merged Spec bankAccountValidation orders API
host: apitest.cybersource.com
basePath: /
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/hal+json;charset=utf-8
tags:
- name: orders
description: "An order is a service that is used for initiating a transaction with itemized details, shipping, billing and buyer information. \n"
paths:
/pts/v2/intents:
post:
summary: Create an Order
description: "A create order request enables you to send the itemized details along with the order. This API can be used by merchants initiating their transactions with the create order API. \n"
tags:
- orders
operationId: createOrder
x-devcenter-metaData:
categoryTag: Payments
parameters:
- name: createOrderRequest
in: body
required: true
schema:
type: object
properties:
clientReferenceInformation:
type: object
properties:
reconciliationId:
type: string
maxLength: 60
description: 'Reference number for the transaction.
Depending on how your Cybersource account is configured, this value could either be provided in the API request or generated by CyberSource.
The actual value used in the request to the processor is provided back to you by Cybersource in the response.
'
processingInformation:
type: object
properties:
processingInstruction:
type: string
maxLength: 36
description: 'The instruction to process an order.
- default value: ''NO_INSTRUCTION''
- ''ORDER_SAVED_EXPLICITLY''
'
authorizationOptions:
type: object
properties:
authType:
type: string
maxLength: 15
description: "Authorization type. Possible values:\n\n - `AUTOCAPTURE`: automatic capture.\n - `STANDARDCAPTURE`: standard capture.\n - `VERBAL`: forced capture. Include it in the payment request for a forced capture. Include it in the capture request for a verbal payment.\n\n#### Asia, Middle East, and Africa Gateway; Cielo; Comercio Latino; and CyberSource Latin American Processing\nSet this field to `AUTOCAPTURE` and include it in a bundled request to indicate that you are requesting an automatic capture. If your account is configured to enable automatic captures, set this field to `STANDARDCAPTURE` and include it in a standard authorization or bundled request to indicate that you are overriding an automatic capture.\n\n#### Forced Capture\nSet this field to `VERBAL` and include it in the authorization request to indicate that you are performing a forced capture; therefore, you receive the authorization code outside the CyberSource system.\n\n#### Verbal Authorization\nSet this field to `VERBAL` and include it in the capture request to indicate that the request is for a verbal authorization.\n\n#### for PayPal ptsV2CreateOrderPost400Response\nSet this field to 'AUTHORIZE' or 'CAPTURE' depending on whether you want to invoke delayed capture or sale respectively.\n"
actionList:
type: array
description: 'Array of actions (one or more) to be included in the order to invoke bundled services along with order.
Possible values:
- `AP_ORDER`: Use this when Alternative Payment Order service is requested.
'
items:
type: string
highRiskTransactionFlag:
type: string
description: 'Indicates if the transaction is flagged as high risk.
'
transactionRetry:
type: string
description: 'Indicates if the transaction is a retry.
'
lastOneHrTransactionCount:
type: string
description: 'The number of transactions in the last one hour.
'
lastOneDayTransactionCount:
type: string
description: 'The number of transactions in the last one day.
'
lastThreeMonthsTxnCount:
type: string
description: 'The number of transactions in the last three months.
'
totalTransactionCount:
type: string
description: 'The total number of transactions.
'
pinVerification:
type: string
description: 'Indicates if PIN verification is required.
'
faceIdVerification:
type: string
description: 'Indicates if face ID verification is required.
'
userPassedVerification:
type: string
description: 'Indicates if the user passed verification.
'
ipAddress:
type: string
description: 'The IP address of the user.
'
transactionDate:
type: string
description: 'The date of the transaction.
'
tangible:
type: string
description: 'Indicates if the transaction involves tangible goods.
'
merchantInformation:
type: object
properties:
merchantDescriptor:
type: object
properties:
name:
type: string
description: 'Your merchant name.
**Note** For Paymentech processor using Cybersource Payouts, the maximum data length is 22.
#### PIN debit
Your business name. This name is displayed on the cardholder''s statement. When you
include more than one consecutive space, extra spaces are removed.
When you do not include this value in your PIN debit request, the merchant name from your account is used.
**Important** This value must consist of English characters.
Optional field for PIN debit credit or PIN debit purchase requests.
#### Airline processing
Your merchant name. This name is displayed on the cardholder''s statement. When you include more than one consecutive space, extra spaces are removed.
**Note** Some airline fee programs may require the original ticket number (ticket identifier) or the ancillary service description in positions 13 through 23 of this field.
**Important** This value must consist of English characters.
Required for captures and credits.
'
email:
type: string
maxLength: 254
description: Email address of the merchant.
cancelUrl:
type: string
maxLength: 255
description: customer would be redirected to this url based on the decision of the transaction
successUrl:
type: string
maxLength: 2048
description: customer would be redirected to this url based on the decision of the transaction
paymentInformation:
type: object
properties:
paymentType:
type: object
properties:
name:
type: string
description: 'A Payment Type is an agreed means for a payee to receive legal tender from a payer. The way one pays for a commercial financial transaction. Examples: Card, Bank Transfer, Digital, Direct Debit.
Possible values:
- `CARD` (use this for a PIN debit transaction)
- `CHECK` (use this for all eCheck payment transactions - ECP Debit, ECP Follow-on Credit, ECP StandAlone Credit)
- `bankTransfer` (use for Online Bank Transafer for methods such as P24, iDeal, Estonia Bank, KCP)
- `localCard` (KCP Local card via Altpay)
- `carrierBilling` (KCP Carrier Billing via Altpay)
'
method:
type: object
properties:
name:
type: string
description: "A Payment Type is enabled through a Method. Examples: Visa, Master Card, ApplePay, iDeal, 7Eleven, alfamart, etc\n#### Via PayPal ptsV2CreateOrderPost201Response\n - 'payPal'\n - 'venmo'\n"
tokenizedPaymentMethod:
type: object
properties:
description:
type: string
maxLength: 128
description: 'Description of the vaulted payment method shown to the buyer during checkout and in their PayPal account.
'
usagePattern:
type: string
maxLength: 30
description: 'Indicates how the merchant will primarily use the vaulted payment method. Valid values:
- "IMMEDIATE": For on-demand, instant payments. These payments are variable in both amount and frequency and will be used to pay for goods or services before they are rendered to the buyer
- "DEFERRED": For post-pay payments; that is, payments for goods or services that have already been rendered to the buyer
- "RECURRING_PREPAID": For recurring payments before services are rendered.
- "RECURRING_POSTPAID": For recurring payments after services are rendered.
- "THRESHOLD_PREPAID": For payments when a pre-defined threshold is reached before services are rendered.
- "THRESHOLD_POSTPAID": For payments when a pre-defined threshold is reached after services are rendered.
'
usageType:
type: string
maxLength: 255
description: 'Indicates the type of vaulting relationship. Valid values:
- "MERCHANT": Single merchant relationship.
- "PLATFORM": Platform hosting multiple merchants.
'
allowMultipleTokens:
type: string
description: 'Create multiple payment tokens for the same payer, merchant/platform combination. This helps to identify customers distinctly even though they may share the same PayPal account.
'
industryType:
type: string
description: 'Indicates the industry type. Possible Values:
- "Events"
- "Ticketing"
- "Fuel"
- "GAMING"
- "DIGITAL GOODS"
- "TELCO"
- "Token Service Providers"
- "Gambling"
- "CFDs"
- "car rental"
- "hotel"
- "transportation"
- "travel package"
- "Cruise Line"
- "P2P"
- "Retail"
- "Food"
- "Groceries"
- "Ride Sharing"
- "Taxi"
- "Remittance"
- "Crypto"
- "Marketplaces"
'
eWallet:
type: object
properties:
accountId:
type: string
maxLength: 26
description: 'The unique ID for a customer generated by PayPal.
'
orderInformation:
type: object
properties:
amountDetails:
type: object
properties:
totalAmount:
type: string
maxLength: 32
description: 'Grand total for the order. This value cannot be negative. You can include a decimal point (.), but you cannot include any other special characters. CyberSource truncates the amount to the correct number of decimal places
'
currency:
type: string
maxLength: 3
description: 'Currency used for the order
'
discountAmount:
type: string
maxLength: 32
description: "Discount amount for the transaction. \n"
shippingAmount:
type: string
maxLength: 32
description: 'Aggregate shipping charges for the transactions.
'
shippingDiscountAmount:
type: string
maxLength: 32
description: "Shipping discount amount for the transaction. \n"
taxAmount:
type: string
maxLength: 32
description: "Total tax amount. \n"
insuranceAmount:
type: string
maxLength: 32
description: "Amount being charged for the insurance fee. \n"
dutyAmount:
type: string
maxLength: 32
description: "Amount being charged as duty amount. \n"
billTo:
type: object
properties:
email:
type: string
minLength: 3
maxLength: 254
description: 'Email address of the PayPal account holder.
'
shipTo:
type: object
properties:
firstName:
type: string
maxLength: 60
description: 'First name of the recipient.
#### Litle
Maximum length: 25
#### All other processors
Maximum length: 60
Optional field.
'
lastName:
type: string
maxLength: 60
description: 'Last name of the recipient.
#### Litle
Maximum length: 25
#### All other processors
Maximum length: 60
Optional field.
'
address1:
type: string
maxLength: 60
description: 'First line of the shipping address.
Required field for authorization if any shipping address information is included in the request; otherwise, optional.
#### Tax Calculation
Optional field for U.S. and Canadian taxes. Not applicable to international and value added taxes.
Billing address objects will be used to determine the cardholder''s location when shipTo objects are not present.
'
address2:
type: string
maxLength: 60
description: 'Second line of the shipping address.
Optional field.
#### Tax Calculation
Optional field for U.S. and Canadian taxes. Not applicable to international and value added taxes.
Billing address objects will be used to determine the cardholder''s location when shipTo objects are not present.
'
locality:
type: string
maxLength: 50
description: 'City of the shipping address.
Required field for authorization if any shipping address information is included in the request and shipping to the U.S. or
Canada; otherwise, optional.
#### Tax Calculation
Optional field for U.S. and Canadian taxes. Not applicable to international and value added taxes.
Billing address objects will be used to determine the cardholder''s location when shipTo objects are not present.
'
administrativeArea:
type: string
maxLength: 50
description: "State or province of the shipping address. Use the [State, Province, and Territory Codes for the United States and Canada](https://developer.cybersource.com/library/documentation/sbc/quickref/states_and_provinces.pdf) (maximum length: 2) \n\nRequired field for authorization if any shipping address information is included in the request and shipping to the U.S.\nor Canada; otherwise, optional.\n\n#### Tax Calculation\nOptional field for U.S. and Canadian taxes. Not applicable to international and value added taxes.\nBilling address objects will be used to determine the cardholder's location when shipTo objects are not present.\n"
postalCode:
type: string
maxLength: 32
description: 'Postal code for the shipping address. The postal code must consist of 5 to 9 digits.
Required field for authorization if any shipping address information is included in the request and
shipping to the U.S. or Canada; otherwise, optional.
When the billing country is the U.S., the 9-digit postal code must follow this format:
[5 digits][dash][4 digits]
Example 12345-6789
When the billing country is Canada, the 6-digit postal code must follow this format:
[alpha][numeric][alpha][space][numeric][alpha][numeric]
Example A1B 2C3
#### American Express Direct
Before sending the postal code to the processor, all nonalphanumeric characters are removed and, if the
remaining value is longer than nine characters, the value is truncated starting from the right side.
#### Tax Calculation
Optional field for U.S. and Canadian taxes. Not applicable to international and value added taxes.
Billing address objects will be used to determine the cardholder''s location when shipTo objects are not present.
'
country:
type: string
description: 'Country of the shipping address. Use the two-character [ISO Standard Country Codes.](http://apps.cybersource.com/library/documentation/sbc/quickref/countries_alpha_list.pdf)
Required field for authorization if any shipping address information is included in the request; otherwise, optional.
#### Tax Calculation
Optional field for U.S., Canadian, international tax, and value added taxes.
Billing address objects will be used to determine the cardholder''s location when shipTo objects are not present.
'
maxLength: 3
method:
type: string
maxLength: 10
description: 'Shipping method for the product. Possible values:
- lowcost: Lowest-cost service
- sameday: Courier or same-day service
- oneday: Next-day or overnight service
- twoday: Two-day service
- threeday: Three-day service
- pickup: Store pick-up
- other: Other shipping method
- none: No shipping method because product is a service or subscription
Required for American Express SafeKey (U.S.).
'
email:
type: string
description: 'Customer''s email address, including the full domain name.
'
phoneNumber:
type: string
description: 'Phone number associated with the shipping address.
'
lineItems:
type: array
maxItems: 10
items:
type: object
properties:
productName:
type: string
maxLength: 255
description: 'For an authorization or capture transaction (`processingOptions.capture` is `true` or `false`),
this field is required when `orderInformation.lineItems[].productCode` is not `default` or one of
the other values that are related to shipping and/or handling.
#### Tax Calculation
Optional field for U.S., Canadian, international tax, and value added taxes.
'
productDescription:
type: string
description: Brief description of item.
productSku:
type: string
maxLength: 255
description: 'Product identifier code. Also known as the Stock Keeping Unit (SKU) code for the product.
For an authorization or capture transaction (`processingOptions.capture` is set to `true` or `false`), this field is required when `orderInformation.lineItems[].productCode` is not set to **default** or one of the other values that are related to shipping and/or handling.
#### Tax Calculation
Optional field for U.S. and Canadian taxes. Not applicable to international and value added taxes.
For an authorization or capture transaction (`processingOptions.capture` is set to `true` or `false`), this field is
required when `orderInformation.lineItems[].productCode` is not `default` or one of the values related to shipping and/or handling.
'
quantity:
type: integer
minimum: 1
maximum: 999999999
default: 1
description: 'Number of units for this order. Must be a non-negative integer.
The default is `1`. For an authorization or capture transaction (`processingOptions.capture` is set to `true` or `false`),
this field is required when `orderInformation.lineItems[].productCode` is not `default` or one of the other values
related to shipping and/or handling.
#### Tax Calculation
Optional field for U.S., Canadian, international tax, and value added taxes.
'
typeOfSupply:
type: string
maxLength: 2
description: "Flag to indicate whether the purchase is categorized as goods or services.\nPossible values:\n\n - 00: goods\n - 01: services\n"
unitPrice:
type: string
maxLength: 15
description: 'Per-item price of the product. This value for this field cannot be negative.
You must include either this field or the request-level field `orderInformation.amountDetails.totalAmount` in your request.
You can include a decimal point (.), but you cannot include any other special characters.
The value is truncated to the correct number of decimal places.
#### DCC with a Third-Party Provider
Set this field to the converted amount that was returned by the DCC provider. You must include either
the 1st line item in the order and this field, or the request-level field `orderInformation.amountDetails.totalAmount` in your request.
#### Tax Calculation
Required field for U.S., Canadian, international and value added taxes.
#### Zero Amount Authorizations
If your processor supports zero amount authorizations, you can set this field to 0 for the
authorization to check if the card is lost or stolen.
#### Maximum Field Lengths
For GPN and JCN Gateway: Decimal (10)
All other processors: Decimal (15)
'
totalAmount:
type: string
maxLength: 13
description: 'Total amount for the item. Normally calculated as the unit price times quantity.
When `orderInformation.lineItems[].productCode` is "gift_card", this is the purchase amount total
for prepaid gift cards in major units.
Example: 123.45 USD = 123
'
taxAmount:
type: string
maxLength: 15
description: "Total tax to apply to the product. This value cannot be negative. The tax amount and the offer amount must\nbe in the same currency. The tax amount field is additive.\n\nThe following example uses a two-exponent currency such as USD:\n\n 1. You include each line item in your request.\n ..- 1st line item has amount=10.00, quantity=1, and taxAmount=0.80\n ..- 2nd line item has amount=20.00, quantity=1, and taxAmount=1.60\n 2. The total amount authorized will be 32.40, not 30.00 with 2.40 of tax included.\n\nOptional field.\n\n#### Airlines processing\nTax portion of the order amount. This value cannot exceed 99999999999999 (fourteen 9s).\nFormat: English characters only.\nOptional request field for a line item.\n\n#### Tax Calculation\nOptional field for U.S., Canadian, international tax, and value added taxes.\n\nNote if you send this field in your tax request, the value in the field will override the tax engine\n"
invoiceDetails:
type: object
properties:
productDescription:
type: string
description: Brief description of item.
senderInformation:
type: object
properties:
account:
type: object
properties:
number:
type: string
description: 'The account number of the sender.
'
firstName:
type: string
description: 'The first name of the sender.
'
lastName:
type: string
description: 'The last name of the sender.
'
email:
type: string
description: 'The email address of the sender.
'
phoneNumber:
type: string
description: 'The phone number of the sender.
'
countryCode:
type: string
description: 'The country code of the sender.
'
createDate:
type: string
description: 'The date when the sender''s account was created.
'
postalCode:
type: string
description: 'The postal code of the sender.
'
riskPopularityScore:
type: string
description: 'The risk popularity score of the sender.
'
eventInformation:
type: object
properties:
date:
type: string
description: 'The date of the event.
'
type:
type: string
description: 'The type of the event.
'
totalTickets:
type: string
description: 'The total number of tickets for the event.
'
travelInformation:
type: object
properties:
agency:
type: object
properties:
startDate:
type: string
description: 'The start date of the agency''s service.
'
endDate:
type: string
description: 'The end date of the agency''s service.
'
changeOfGuest:
type: string
description: 'Indicates if there is a change of guest.
'
countryCode:
type: string
description: 'The country code of the agency.
'
locality:
type: string
description: 'The locality of the agency.
'
postalCode:
type: string
description: 'The postal code of the agency.
'
journeyType:
type: string
description: 'The type of journey.
'
actualFinalDestination:
type: string
description: 'The actual final destination of the travel.
'
recipientInformation:
type: object
properties:
accountId:
type: string
description: 'The account ID of the recipient.
'
createDate:
type: string
description: 'The date when the recipient''s account was created.
'
email:
type: string
description: 'The email address of the recipient
'
countryCode:
# --- truncated at 32 KB (83 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cybersource/refs/heads/main/openapi/cybersource-orders-api-openapi.yml