CyberSource Invoices API
Offer your customers a simple, convenient, and fast way to pay with the new online invoicing tool.
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 Invoices API
host: apitest.cybersource.com
basePath: /
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/hal+json;charset=utf-8
tags:
- name: Invoices
description: 'Offer your customers a simple, convenient, and fast way to pay with the new online invoicing tool.
'
paths:
/invoicing/v2/invoices:
post:
tags:
- Invoices
summary: Create a New Invoice
description: 'The invoicing product enables you to bill any customer with an email address and accept digital payments securely from any connected device. You can either use the system generated email or use the invoice payment link in your own communication. You can add discounts and taxes for the entire invoice or for each line item. To customize the invoice to match your brand see [Invoice Settings](https://developer.cybersource.com/api-reference-assets/index.html#invoicing_invoice-settings_update-invoice-settings). The invoice payment page uses Unified Checkout to process the payments.
The availability of API features for a merchant can depend on the portfolio configuration and may need to be enabled at the portfolio level before they can be added to merchant accounts.'
operationId: createInvoice
x-devcenter-metaData:
categoryTag: Invoicing
developerGuides: https://developer.cybersource.com/docs/cybs/en-us/invoicing/developer/all/rest/invoicing/Introduction.html
consumes:
- application/json;charset=utf-8
produces:
- application/json
- application/hal+json
- application/json;charset=utf-8
- application/hal+json;charset=utf-8
parameters:
- name: createInvoiceRequest
in: body
required: true
schema:
type: object
required:
- invoiceInformation
- orderInformation
properties:
clientReferenceInformation:
type: object
properties:
partner:
type: object
properties:
developerId:
type: string
maxLength: 8
description: 'Identifier for the developer that integrated a partner solution with Cybersource. Send this value with all requests that are sent through a partner solution built by that developer. Cybersource assigns the ID to the developer.
**Note** A developerId set to 999 means the submitted developer ID is incorrect.
'
solutionId:
type: string
maxLength: 8
description: 'Identifier for the partner that integrated with Cybersource. Send this value with all requests sent through the partner solution. Cybersource assigns the ID to the partner.
**Note** A solutionId set to 999 means the submitted solutionId is incorrect.
'
customerInformation:
type: object
description: Contains all of the customer-related fields for the invoice.
properties:
name:
type: string
maxLength: 100
description: Payer name for the invoice.
email:
type: string
maxLength: 255
description: 'Customer''s email address, including the full domain name.
#### CyberSource through VisaNet
Credit card networks cannot process transactions that contain non-ASCII characters. CyberSource through VisaNet accepts and stores non-ASCII characters correctly and displays them correctly in reports. However, the limitations of the credit card networks prevent CyberSource through VisaNet from transmitting non-ASCII characters to the credit card networks. Therefore, CyberSource through VisaNet replaces non-ASCII characters with meaningless ASCII characters for transmission to the credit card networks.
**Important** It is your responsibility to determine whether a field is required for the transaction you are requesting.
#### Invoicing
Email address for the customer for sending the invoice. If the invoice is in SENT status and email is updated, the old email customer payment link won''t work and you must resend the invoice with the new payment link.
#### Chase Paymentech Solutions
Optional field.
#### Credit Mutuel-CIC
Optional field.
#### OmniPay Direct
Optional field.
#### SIX
Optional field.
#### TSYS Acquiring Solutions
Required when `processingInformation.billPaymentOptions.billPayment=true` and `pointOfSaleInformation.entryMode=keyed`.
#### Worldpay VAP
Optional field.
#### All other processors
Not used.
'
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.
'
company:
type: object
properties:
name:
type: string
maxLength: 60
description: 'Name of the customer''s company.
**CyberSource through VisaNet**
Credit card networks cannot process transactions that contain non-ASCII characters. CyberSource through VisaNet accepts and stores non-ASCII characters correctly and displays them correctly in reports. However, the limitations of the credit card networks prevent CyberSource through VisaNet from transmitting non-ASCII characters to the credit card networks. Therefore, CyberSource through VisaNet replaces non-ASCII characters with meaningless ASCII characters for transmission to the credit card networks.
'
processingInformation:
type: object
description: Contains processing information, such as collection details.
properties:
requestPhone:
type: boolean
description: Collect the payers phone number during the payment.
default: false
requestShipping:
type: boolean
description: Collect the payers shipping address during the payment.
default: false
invoiceInformation:
type: object
required:
- dueDate
- description
description: Contains all of the invoice-specific fields, such as the invoice number and due date.
properties:
invoiceNumber:
type: string
description: Invoice Number.
description:
type: string
maxLength: 2000
description: The description included in the invoice.
dueDate:
type: string
maxLength: 10
format: date
description: 'The invoice due date. This field is required for creating an invoice.
Format: `YYYY-MM-DD`, where `YYYY` = year, `MM` = month, and `DD` = day
'
expirationDate:
type: string
maxLength: 10
format: date
description: 'Define an expiration date for the link.
Format: `YYYY-MM-DD`, where `YYYY` = year, `MM` = month, and `DD` = day
'
sendImmediately:
type: boolean
description: If set to `true`, we send the invoice immediately. If set to `false`, the invoice remains in draft mode.
default: false
allowPartialPayments:
type: boolean
description: If set to `true`, the payer can make a partial invoice payment.
default: false
deliveryMode:
type: string
description: "If this field is set to 'None', an invoice will be generated with the status 'CREATED', but no email will be dispatched. \n\nPossible values: \n - `None` \n - `Email` \n \n"
orderInformation:
type: object
required:
- amountDetails
description: Contains all of the order-related fields, such as the amount and line item details.
properties:
amountDetails:
type: object
required:
- currency
- totalAmount
description: Contains all of the amount-related fields.
properties:
totalAmount:
type: string
maxLength: 19
description: "Grand total for the order. This value cannot be negative. You can include a decimal point (.), but no other special characters.\nCyberSource truncates the amount to the correct number of decimal places.\n\n**Note** For CTV, FDCCompass, Paymentech processors, the maximum length for this field is 12.\n\n**Important** Some processors have specific requirements and limitations, such as maximum amounts and maximum field lengths.\n\nIf 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. \n\n#### Card Present\nRequired to include either this field or `orderInformation.lineItems[].unitPrice` for the order.\n\n#### Invoicing / Pay By Link\nRequired for creating a new invoice or payment link.\n\n#### PIN Debit\nAmount you requested for the PIN debit purchase. This value is returned for partial authorizations. The issuing bank can approve a partial amount if the balance on the debit card is less than the requested transaction amount.\n\nRequired field for PIN Debit purchase and PIN Debit credit requests.\nOptional field for PIN Debit reversal requests.\n\n#### GPX\nThis field is optional for reversing an authorization or credit; however, for all other processors, these fields are required.\n\n#### DCC with a Third-Party Provider\nSet this field to the converted amount that was returned by the DCC provider. You must include either this field or the 1st line item in the order and the specific line-order amount in your request. \n\n#### DCC for First Data\nNot used.\n"
currency:
type: string
maxLength: 3
description: 'Currency used for the order. Use the three-character [ISO Standard Currency Codes.](http://apps.cybersource.com/library/documentation/sbc/quickref/currencies.pdf)
#### Used by
**Authorization**
Required field.
**Authorization Reversal**
For an authorization reversal (`reversalInformation`) or a capture (`processingOptions.capture` is set to `true`), you must use the same currency that you used in your payment authorization request.
#### PIN Debit
Currency for the amount you requested for the PIN debit purchase. This value is returned for partial authorizations. The issuing bank can approve a partial amount if the balance on the debit card is less than the requested transaction amount. For the possible values, see the [ISO Standard Currency Codes](https://developer.cybersource.com/library/documentation/sbc/quickref/currencies.pdf).
Returned by PIN debit purchase.
For PIN debit reversal requests, you must use the same currency that was used for the PIN debit purchase or PIN debit credit that you are reversing.
For the possible values, see the [ISO Standard Currency Codes](https://developer.cybersource.com/library/documentation/sbc/quickref/currencies.pdf).
Required field for PIN Debit purchase and PIN Debit credit requests.
Optional field for PIN Debit reversal requests.
#### GPX
This field is optional for reversing an authorization or credit.
#### DCC for First Data
Your local currency.
#### Tax Calculation
Required for international tax and value added tax only.
Optional for U.S. and Canadian taxes.
Your local currency.
'
discountAmount:
example: '10.00'
type: string
maxLength: 15
description: 'Total discount amount applied to the order.
'
discountPercent:
example: '10'
type: string
maxLength: 7
description: The total discount percentage applied to the order.
subAmount:
type: string
maxLength: 25
description: Sub-amount of the order.
minimumPartialAmount:
type: string
description: The minimum partial amount required to pay the invoice.
taxDetails:
type: object
description: Contains all of the tax-related fields for the order.
properties:
type:
type: string
description: 'Indicates the type of tax data for the _taxDetails_ object.
Possible values:
- `alternate`
- `local`
- `national`
- `vat`
- `other`
- `green`
'
amount:
type: string
maxLength: 13
description: 'Indicates the amount of tax based on the `type` field as described in the table below:
| type | type description |
| ------------- |:-------------:|
| `alternate` | Total amount of alternate tax for the order. |
| `local` | Sales tax for the order. |
| `national` | National tax for the order. |
| `vat` | Total amount of value added tax (VAT) included in the order. |
| `other` | Other tax. |
| `green` | Green tax amount for Korean Processing. |
'
rate:
type: string
maxLength: 6
description: 'Rate of VAT or other tax for the order.
Example 0.040 (=4%)
Valid range: 0.01 to 0.99 (1% to 99%, with only whole percentage values accepted; values with additional
decimal places will be truncated)
'
freight:
type: object
description: Contains all of the shipping-related fields for the order.
properties:
amount:
type: string
maxLength: 13
description: 'Total freight or shipping and handling charges for the order. When you include this field in your request, you
must also include the **totalAmount** field.
'
taxable:
type: boolean
description: "Flag that indicates whether an order is taxable. This value must be true if the sum of all _lineItems[].taxAmount_ values > 0.\n\nIf you do not include any `lineItems[].taxAmount` values in your request, CyberSource does not include\n`invoiceDetails.taxable` in the data it sends to the processor.\n\nPossible values:\n - **true**\n - **false**\n"
taxRate:
description: 'Shipping Tax rate applied to the freight amount.
**Visa**: Valid range is 0.01 to 0.99 (1% to 99%, with only whole percentage values accepted; values with additional
decimal places will be truncated).
**Mastercard**: Valid range is 0.00001 to 0.99999 (0.001% to 99.999%).
'
type: string
maxLength: 7
lineItems:
type: array
description: List of the line items from the order.
maxItems: 30
items:
type: object
description: Line item from the order.
properties:
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.
'
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.
'
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.
'
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)
'
discountAmount:
example: '10.00'
type: string
maxLength: 13
description: Discount applied to the item.
discountPercent:
example: '10'
type: string
maxLength: 6
description: 'Rate the item is discounted. Maximum of 2 decimal places.
Example 5.25 (=5.25%)
'
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"
taxRate:
type: string
maxLength: 7
description: 'Valid range: 1% to 99%, with only whole percentage values accepted; values with additional
decimal places will be truncated
For processor-specific details, see the alternate_tax_amount, vat_rate, vat_tax_rate, local_tax, national_tax, vat_tax_amount or other_tax#_rate field descriptions in the Level II and Level III Processing Using the SCMP API Guide.
'
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
'
merchantDefinedFieldValues:
type: array
items:
type: object
properties:
definitionId:
type: integer
format: int64
value:
type: string
example:
clientReferenceInformation:
partner:
developerId: '3435'
solutionId: '83745'
customerInformation:
name: Tanya Lee
firstName: Tanya
lastName: Lee
email: tanya.lee@my-email.world
merchantCustomerId: '1234'
company:
name: ABC
processingInformation:
requestPhone: false
requestShipping: false
invoiceInformation:
invoiceNumber: '98753'
description: This is a test invoice
dueDate: '2019-07-11'
expirationDate: '2028-08-11'
sendImmediately: true
allowPartialPayments: true
deliveryMode: email
orderInformation:
amountDetails:
totalAmount: '2623.64'
currency: USD
discountAmount: '126.08'
discountPercent: '5.0'
subAmount: '2749.72'
minimumPartialAmount: '20'
taxDetails:
type: State Tax
amount: '208.04'
rate: '8.25'
freight:
amount: '20.00'
taxable: true
taxRate: '10'
lineItems:
- productSku: P653727383
productName: First line item's name
unitPrice: '12.05'
quantity: '20'
discountAmount: '13.04'
discountPercent: '5.0'
taxAmount: '0.0'
taxRate: '0.0'
totalAmount: '247.86'
merchantDefinedFieldValues:
- definitionId: 123
value: Some value
- definitionId: 456
value: Another value
responses:
'201':
description: Created.
schema:
title: invoicingV2InvoicesPost201Response
type: object
properties:
_links:
type: object
properties:
self:
type: object
properties:
href:
type: string
description: This is the endpoint of the resource that was created by the successful request.
method:
type: string
description: '`method` refers to the HTTP method that you can send to the `self` endpoint to retrieve details of the resource.'
update:
type: object
properties:
href:
type: string
description: This is the endpoint of the resource that was created by the successful request.
method:
type: string
description: '`method` refers to the HTTP method that you can send to the `self` endpoint to retrieve details of the resource.'
deliver:
type: object
properties:
href:
type: string
description: This is the endpoint of the resource that was created by the successful request.
method:
type: string
description: '`method` refers to the HTTP method that you can send to the `self` endpoint to retrieve details of the resource.'
cancel:
type: object
properties:
href:
type: string
description: This is the endpoint of the resource that was created by the successful request.
method:
type: string
description: '`method` refers to the HTTP method that you can send to the `self` endpoint to retrieve details of the resource.'
id:
type: string
maxLength: 26
description: 'An unique identification number generated by Cybersource to identify the submitted request. Returned by all services.
It is also appended to the endpoint of the resource.
On incremental authorizations, this value with be the same as the identification number returned in the original authorization response.
'
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 invoice.
Possible values:
- DRAFT
- CREATED
- SENT
- PARTIAL
- PAID
- CANCELED
- PENDING
'
customerInformation:
type: object
description: Contains all of the customer-related fields for the invoice.
properties:
name:
type: string
maxLength: 100
description: Payer name for the invoice.
email:
type: string
maxLength: 255
description: 'Customer''s email address, including the full domain name.
#### CyberSource through VisaNet
Credit card networks cannot process transactions that contain non-ASCII characters. CyberSource through VisaNet accepts and stores non-ASCII characters correctly and displays them correctly in reports. However, the limitations of the credit card networks prevent CyberSource through VisaNet from transmitting non-ASCII characters to the credit card networks. Therefore, CyberSource through VisaNet replaces non-ASCII characters with meaningless ASCII characters for tr
# --- truncated at 32 KB (321 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cybersource/refs/heads/main/openapi/cybersource-invoices-api-openapi.yml