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: type: string description: 'The country code of the recipient. ' businessName: type: string description: 'The business name of the recipient. ' riskPopularityScore: type: string description: 'The risk popularity score of the recipient. ' example: orderInformation: amountDetails: totalAmount: '102.21' currency: USD shipTo: country: US lastName: VDP address1: 201 S. Division St. postalCode: 48104-2201 locality: Ann Arbor administrativeArea: MI firstName: RTS invoiceDescription: productDescription: Description of the product invoice merchantInformation: merchantDescriptor: name: Merchant1 email: merchant1@gmail.com processingInformation: processingInstruction: NO_INSTRUCTION authorizationOptions: authType: AUTHORIZE actionList: AP_ORDER paymentInformation: paymentType: method: name: payPal name: ewallet responses: '201': description: Successful response. schema: title: ptsV2CreateOrderPost201Response type: object properties: submitTimeUtc: type: string description: 'Time of request in UTC. Format: `YYYY-MM-DDThh:mm:ssZ` **Example** `2016-08-11T22:47:57Z` equals August 11, 2016, at 22:47:57 (10:47:57 p.m.). The `T` separates the date and the time. The `Z` indicates UTC. Returned by Cybersource for all services. ' updateTimeUtc: type: string description: 'The date and time when the request was last updated. **Example** `2016-08-11T22:47:57Z` equals August 11, 2016, at 22:47:57 (10:47:57 p.m.). ' status: type: string description: "The status of the submitted transaction.\nPossible values:\n - CREATED\n - SAVED\n - APPROVED\n - VOIDED\n - COMPLETED\n - PAYER_ACTION_REQUIRED\n" 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. ' clientReferenceInformation: type: object properties: code: type: string maxLength: 59 description: 'Merchant-generated order reference or tracking number. It is recommended that you send a unique value for each transaction so that you can perform meaningful searches for the transaction. #### Used by **Authorization** Required field. #### PIN Debit Requests for PIN debit reversals need to use the same merchant reference number that was used in the transaction that is being reversed. Required field for all PIN Debit requests (purchase, credit, and reversal). #### FDC Nashville Global Certain circumstances can cause the processor to truncate this value to 15 or 17 characters for Level II and Level III processing, which can cause a discrepancy between the value you submit and the value included in some processor reports. ' processorInformation: type: object properties: transactionId: type: string maxLength: 255 description: 'Network transaction identifier (TID). You can use this value to identify a specific transaction when you are discussing the transaction with your processor. Not all processors provide this value. Returned by the authorization service. #### PIN debit Transaction identifier generated by the processor. Returned by PIN debit credit. #### GPX Processor transaction ID. #### Cielo For Cielo, this value is the non-sequential unit (NSU) and is supported for all transactions. The value is generated by Cielo or the issuing bank. #### Comercio Latino For Comercio Latino, this value is the proof of sale or non-sequential unit (NSU) number generated by the acquirers Cielo and Rede, or the issuing bank. #### CyberSource through VisaNet and GPN For details about this value for CyberSource through VisaNet and GPN, see "processorInformation.networkTransactionId" in [REST API Fields](https://developer.cybersource.com/content/dam/docs/cybs/en-us/apifields/reference/all/rest/api-fields.pdf) #### Moneris This value identifies the transaction on a host system. It contains the following information: - Terminal used to process the transaction - Shift during which the transaction took place - Batch number - Transaction number within the batch You must store this value. If you give the customer a receipt, display this value on the receipt. **Example** For the value 66012345001069003: - Terminal ID = 66012345 - Shift number = 001 - Batch number = 069 - Transaction number = 003 ' networkTransactionId: type: string description: Same value as `processorInformation.transactionId` paymentUrl: type: string maxLength: 2048 description: Direct the customer to this URL to complete the payment. paymentInformation: type: object properties: eWallet: type: object properties: accountId: type: string maxLength: 26 description: The ID of the customer, passed in the return_url field by PayPal after customer approval. fundingSource: type: string maxLength: 30 description: Payment mode for the authorization or order transaction.  INSTANT_TRANSFER  MANUAL_BANK_TRANSFER  DELAYED_TRANSFER  ECHECK  UNRESTRICTED (default)—this value is available only when configured by PayPal for the merchant. INSTANT fundingSourceSale: type: string maxLength: 30 description: 'Payment method for the unit purchase. Possible values: - `UNRESTRICTED (default)—this value is only available if configured by PayPal for the merchant.` - `INSTANT` ' userName: type: string description: 'The Venmo user name chosen by the user, also known as a Venmo handle. ' buyerInformation: type: object properties: merchantCustomerId: type: string maxLength: 100 description: 'Your identifier for the customer. When a subscription or customer profile is being created, the maximum length for this field for most processors is 30. Otherwise, the maximum length is 100. #### Comercio Latino For recurring payments in Mexico, the value is the customer''s contract number. Note Before you request the authorization, you must inform the issuer of the customer contract numbers that will be used for recurring transactions. #### Worldpay VAP For a follow-on credit with Worldpay VAP, CyberSource checks the following locations, in the order given, for a customer account ID value and uses the first value it finds: 1. `customer_account_id` value in the follow-on credit request 2. Customer account ID value that was used for the capture that is being credited 3. Customer account ID value that was used for the original authorization If a customer account ID value cannot be found in any of these locations, then no value is used. ' example: submitTimeUtc: 2024-06-01T071957Z updateTimeUtc: 2024-06-01T071957Z status: CREATED reconciliationId: 39570726X3E1LBQR clientReferenceInformation: code: DEFAULT processorInformation: transactionId: 1234qwerty1234 '400': description: Invalid request. schema: type: object title: ptsV2CreateOrderPost400Response properties: submitTimeUtc: type: string description: 'Time of request in UTC. Format: `YYYY-MM-DDThh:mm:ssZ` **Example** `2016-08-11T22:47:57Z` equals August 11, 2016, at 22:47:57 (10:47:57 p.m.). The `T` separates the date and the time. The `Z` indicates UTC. Returned by Cybersource for all services. ' status: type: string description: "The status of the submitted transaction.\n\nPossible values:\n - INVALID_REQUEST\n" message: type: string description: The detail message related to the status and reason listed above. details: type: array items: type: object properties: field: type: string description: This is the flattened JSON object field name/path that is either missing or invalid. reason: type: string description: "Possible reasons for the error.\n\nPossible values:\n - MISSING_FIELD\n - INVALID_DATA\n" '502': description: Unexpected system error or system timeout. schema: title: ptsV2CreateOrderPost502Response type: object properties: submitTimeUtc: type: string description: 'Time of request in UTC. Format: `YYYY-MM-DDThh:mm:ssZ` **Example** `2016-08-11T22:47:57Z` equals August 11, 2016, at 22:47:57 (10:47:57 p.m.). The `T` separates the date and the time. The `Z` indicates UTC. Returned by Cybersource for all services. ' status: type: string description: "The status of the submitted transaction.\n\nPossible values:\n - SERVER_ERROR\n" reason: type: string description: "The reason of the status.\n\nPossible values:\n - SYSTEM_ERROR\n - SERVER_TIMEOUT\n - SERVICE_TIMEOUT\n" message: type: string description: The detail message related to the status and reason listed above. x-example: example0: summary: Create Order sample-name: Create Order value: orderInformation: amountDetails: totalAmount: '102.21' currency: USD shipTo: country: US lastName: VDP address1: 201 S. Division St. postalCode: 48104-2201 locality: Ann Arbor administrativeArea: MI firstName: RTS merchantInformation: merchantDescriptor: name: Merchant1 email: merchant1@gmail.com processingInformation: processingInstruction: NO_INSTRUCTION authorizationOptions: authType: AUTHORIZE actionList: AP_ORDER paymentInformation: paymentType: method: name: payPal name: ewallet /pts/v2/intents/{id}: patch: summary: Update an Order description: 'This API can be used in two flavours - for updating the order as well as saving the order. ' tags: - orders operationId: updateOrder x-devcenter-metaData: categoryTag: Payments parameters: - name: id in: path description: The ID returned from the original create order response. required: true type: string - name: updateOrderRequest 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. ' 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" 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. 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. 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" processingInformation: type: object properties: actionList: type: array description: 'Array of actions (one or more) to be included in the void to invoke bundled services along with void. Possible values: - `AP_UPDATE_ORDER`: Use this when Alternative Payment Update order service is requested. - `AP_EXTEND_ORDER`: Use this when Alternative Payment extend order service is requested. ' items: type: string example: orderInformation: amountDetails: totalAmount: '102.21' currency: USD shipTo: country: US lastName: VDP address1: 201 S. Division St. postalCode: 48104-2201 locality: Ann Arbor administrativeArea: MI firstName: RTS invoiceDescription: productDescription: Description of the product invoice merchantInformation: merchantDescriptor: name: Merchant1 email: merchant1@gmail.com paymentInformation: paymentType: method: name: payPal name: ewallet responses: '201': description: Successful response. schema: title: ptsV2UpdateOrderPatch201Response type: object properties: status: type: string description: "The status of the submitted transaction.\nPossible values:\n - CREATED\n - SAVED\n - APPROVED\n - VOIDED\n - COMPLETED\n - PAYER_ACTION_REQUIRED\n" processorInformation: type: object properties: transactionId: type: string maxLength: 255 description: 'Network transaction identifier (TID). You can use this value to identify a specific transaction when you are discussing the transaction with your processor. Not all processors provide this value. Returned by the authorization service. #### PIN debit Transaction identifier generated by the processor. Returned by PIN debit credit. #### GPX Processor transaction ID. #### Cielo For Cielo, this value is the non-sequential unit (NSU) and is supported for all transactions. The value is generated by Cielo or the issuing bank. #### Comercio Latino For Comercio Latino, this value is the proof of sale or non-sequential unit (NSU) number generated by the acquirers Cielo and Rede, or the issuing bank. #### CyberSource through VisaNet and GPN For details about this value for CyberSource through VisaNet and GPN, see "processorInformation.networkTransactionId" in [REST API Fields](https://developer.cybersource.com/content/dam/docs/cybs/en-us/apifields/reference/all/rest/api-fields.pdf) #### Moneris This value identifies the transaction on a host system. It contains the following information: - Terminal used to process the transaction - Shift during which the transaction took place - Batch number - Transaction number within the batch You must store this value. If you give the customer a receipt, display this value on the receipt. **Example** For the value 66012345001069003: - Terminal ID = 66012345 - Shift number = 001 - Batch number = 069 - Transaction number = 003 ' networkTransactionId: type: string description: Same value as `processorInformation.transactionId` paymentUrl: type: string maxLength: 2048 description: Direct the customer to this URL to complete the payment. example: status: COMPLETED processorInformation: transactionId: 1234qwerty1234 networkTransactionId: 123qwerty123 '400': description: Invalid request. schema: type: object title: ptsV2UpdateOrderPatch400Response properties: submitTimeUtc: type: string description: 'Time of request in UTC. Format: `YYYY-MM-DDThh:mm:ssZ` **Example** `2016-08-11T22:47:57Z` equals August 11, 2016, at 22:47:57 (10:47:57 p.m.). The `T` separates the date and the time. The `Z` indicates UTC. Returned by Cybersource for all services. ' status: type: string description: "The status of the submitted transaction.\n\nPossible values:\n - INVALID_REQUEST\n" message: type: string description: The detail message related to the status and reason listed above. details: type: array items: type: object properties: field: type: string description: This is the flattened JSON object field name/path that is either missing or invalid. reason: type: string description: "Possible reasons for the error.\n\nPossible values:\n - MISSING_FIELD\n - INVALID_DATA\n" '502': description: Unexpected system error or system timeout. schema: title: ptsV2UpdateOrderPatch502Response type: object properties: submitTimeUtc: type: string description: 'Time of request in UTC. Format: `YYYY-MM-DDThh:mm:ssZ` **Example** `2016-08-11T22:47:57Z` equals August 11, 2016, at 22:47:57 (10:47:57 p.m.). The `T` separates the date and the time. The `Z` indicates UTC. Returned by Cybersource for all services. ' status: type: string description: "The status of the submitted transaction.\n\nPossible values:\n - SERVER_ERROR\n" reason: type: string description: "The reason of the status.\n\nPossible values:\n - SYSTEM_ERROR\n - SERVER_TIMEOUT\n - SERVICE_TIMEOUT\n" message: type: string description: The detail message related to the status and reason listed above. x-example: example0: summary: Incremental Authorization sample-name: Incremental Authorization value: clientReferenceInformation: code: TC50171_3 processingInformation: authorizationOptions: initiator: storedCredentialUsed: true orderInformation: amountDetails: additionalAmount: '22.49' currency: USD merchantInformation: transactionLocalDateTime: 20191002080000 travelInformation: duration: '4' x-devcenter-metaData: categoryTagArray: - name: Payments description: For more information about Payments transactions, see the [Payments Developer Guides Page](https://developer.cybersource.com/docs/cybs/en-us/payments/developer/ctv/rest/payments/payments-intro.html). - name: Transaction_Batches description: For more information about Transaction Batches, see the [Transaction Batches Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-transaction-batch-api/txn_batch_api_intro.html). - name: eCheck_AVS description: For more information about eCheck Account Validation, see the [Account Validation Developer Guides Page](https://...). - name: Token_Management description: For more information about the Token Management Service (TMS) see the [Token Management Developer Guide](https://developer.cybersource.com/docs/cybs/en-us/tms/developer/all/rest/tms/tms-overview.html) - name: Flex_Microform description: Microform Integration is a lightweight acceptance solution designed to safely and securely accept payment information within your web page. Microform is designed to a be embedded seamlessly within your existing webpage experience, blending in with your existing acceptance form. This solution allows for the replacement of sensitive payment date with a transient token (a short lived reference to the sensitive payment data). For more information about Flex Microform transactions, see the [Flex Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-flex/SAFlexibleToken.html). For examples on how to integrate Flex Microform within your webpage please see our [GitHub Flex Samples](https://github.com/CyberSource?q=flex&type=&language=) - name: Flex_API description: For more information about Flex API, please see [Developer Guides Page](https://developer.cybersource.com/docs/cybs/en-us/digital-accept-flex/developer/all/rest/digital-accept-flex/da-flex-api-intro.html). - name: Risk_Management - name: Payouts description: 'For more information about Payouts, see the [Payouts Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-payouts/Introduction.html). ' - name: Installments description: For more information about Installment contact Cybersource Support. For Visa installments contact VISthroughCYBS@visa.com - name: Recurring_Billing_Subscriptions description: For more information about Recurring Billing, see the [Recurring Billing Developer Guide](https://developer.cybersource.com/docs/cybs/en-us/recurring-billing/developer/all/rest/recurring-billing-developer/recur-bill-services-intro.html). - name: BIN_Lookup description: 'The BIN Lookup Service is a versatile business tool that provides card network agnostic solution designed to ensure frictionless transaction experience by utilizing up-to-date Bank Identification Number (BIN) attributes sourced from multiple global and regional data sources. This service helps to improve authorization rates by helping to route transactions to the best-suited card network, minimizes fraud through card detail verification and aids in regulatory compliance by identifying card properties. The service is flexible and provides businesses with a flexible choice of inputs such as primary account number (PAN), network token from major networks (such as Visa, American Express, Discover and regional networks) which includes device PAN (DPAN), and all types of tokens generated via CyberSource Token Management Service (TMS). Currently, the range of available credentials is contingent on the networks enabled for the business entity. Therefore, the network information specified in this documentation is illustrative and subject to personalized offerings for each reseller or merchant. ' - name: Transaction_Details description: For more information about Transaction Details, see the [Transaction Details Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-txn-search-details-rest-api-dev-guide-102718/txn_details_api.html). - name: Transaction_Search description: For more information about Transaction Search, see the [Transaction Search Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-txn-search-details-rest-api-dev-guide-102718/txn_search_api.html). - name: Reporting description: 'For more information about Reporting, see the [Reporting Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-reporting-rest-api-dev-guide-102718/reporting_api.html). ' - name: Secure_File_Share description: For more information about Secure File Share, see the [Secure File Share Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-secure-file-share-api-102718/secure_file_share_api_intro.html). - name: Invoices description: For more information about Invoicing, see the [Invoicing Developer Guide](https://developer.cybersource.com/docs/cybs/en-us/invoicing/developer/all/rest/invoicing/Introduction.html). - name: Pay_By_Link description: For more information about PayByLink, see the [PBL Developer Guide](https://developer.cybersource.com/docs/cybs/en-us/boarding/user/all/rest/boarding/templates-matrix-intro/templates-matrix-pay-by-link.html). - name: User_Management description: For more information about User Management, see the [User Managment Developer Guides Page](https://developer.cybersource.com/api/developer-guides/dita-user-management-api-102718/user_management_api_intro.html). - name: Value_Added_Service - name: Fee Service - name: Merchant_Boarding description: For more information about Merchant Boarding, please see [Developer Guides Page](https://developer.cybersource.com/api/developer-guides/Merchant-Boarding-API_ditamap/Merchant-Boarding-API.html). - name: Webhooks description: For more information about Webhooks, please see [Developer Guides Page](https://developer.cybersource.com/docs/cybs/en-us/webhooks/implementation/all/rest/webhooks/wh-fg-intro.html). - name: Unified_Checkout description: For more information about Unified Checkout, see the [Unified Checkout Developer Guides Page](https://developer.cybersource.com/docs/cybs/en-us/unified-checkout/developer/all/rest/unified-checkout/uc-intro.html). - name: Unified_Checkoutv1 description: For more information about Unified Checkout, see the [Unified Checkout Developer Guides Page](https://developer.cybersource.com/docs/cybs/en-us/unified-checkout/developer/all/rest/unified-checkout/uc-about-guide.html). - name: Account_Updater description: For more information about Account Updater, see the [Account Updater Developer Guides Page:](https://developer.cybersource.com/library/documentation/dev_guides/Account_Updater_UG/html/index.html). - name: Visa_Bank_Account_Validation description: 'The Visa Bank Account Validation Service is a new standalone product designed to validate customer''s routing and bank account number combination for ACH transactions. Merchant''s can use this standalone product to validate their customer''s account prior to processing an ACH transaction against the customer''s account to comply with Nacha''s account validation mandate for Web-debit transactions. ' - name: Currency Conversion description: 'Empower global transactions with transparency and choice. Our Dynamic Currency Conversion API lets merchants offer customers the option to pay in their home currency at checkout, delivering real-time exchange rates and clear cost disclosure. **Key Benefits:** - **Enhanced Customer Experience:** Provide clarity and convenience for international shoppers. - **Real-Time Rates:** Accurate currency conversion with all the data required for acquirers and their merchants to maintain compliance with card network rules. - **Seamless Integration:** Flexible API endpoints for rate lookup, authorization, and capture. - **Regulatory Compliance:** Provides the data required for acquirers and merchants to meet and maintain card scheme requirements for disclosure and consent. Ideal for merchants and payment partners seeking to boost trust and conversion in cross-border commerce. **Key Features:** - **Rate Lookup:** Retrieves the most up-to-date exchange rate for eligible cards before authorization. - **Currency Choice:** Enables the merchant to offer customers the option to select between the merchant''s local currency and their card''s billing currency. - **Compliance:** Ensures merchants have the data required to adhere to card network regulations; exchange rates, markups, etc. **Supported Scenarios:** - Dynamic Currency Conversion when cardholder''s billing currency differs from merchant''s pricing currency. - Merchant and acquirer must support the cardholder''s billing currency. **Core API Endpoints:** **Currency Conversion API** Returns eligibility and exchange rate details, including: - exchangeRate - marginRate - reconciliationId and Id (for subsequent payment requests) **Payment Authorization with DCC*** POST /pts/v2/payments Required fields include: - orderInformation.amountDetails.currency - orderInformation.amountDetails.originalCurrency - orderInformation.amountDetails.originalAmount - orderInformation.amountDetails.exchangeRate - currencyConversion.indicator (e.g., 1 = Converted, 2 = Nonconvertible, 3 = Declined) **Capture with DCC*** POST /pts/v2/payments/{id}/captures Maps from original authorization and includes original and converted amounts. **Refund with DCC*** POST /pts/v2/captures/{id}/refunds Maps from original authorization and includes original and converted amounts. *Note: DCC is only supported on select processors. Contact your acquirer or account manager for more information. **Compliance & Disclosure:** Merchants must: - Adhere to card network rules for Dynamic Currency Conversion (DCC) transactions. - Display the converted amount, exchange rate, and markup percentage and other required disclosures. - Obtain explicit cardholder consent before applying DCC. - Work with your acquirer to obtain full set of compliance requirements. For more information, see the [Currency Conversion Developer Guide](https://developer.cybersource.com/docs/cybs/en-us/currency-conversion/developer/all/rest/currency-conversion/cc-intro.html). ' - name: Intelligent_Commerce_Connect description: For more information about Intelligent Commerce Cross Network Service API, please see [Developer Guides](https://developer.cybersource.com/docs/cybs/en-us/intelligent-commerce/developer/all/rest/intelligent-commerce/intelligent-commerce-about-guide.html).