CyberSource Payment Links API
Offer your customers a simple, convenient, and fast way to pay with the new online pay by link 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 Payment Links API
host: apitest.cybersource.com
basePath: /
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/hal+json;charset=utf-8
tags:
- name: Payment Links
description: 'Offer your customers a simple, convenient, and fast way to pay with the new online pay by link tool.
'
paths:
/ipl/v2/payment-links:
post:
tags:
- Payment Links
summary: Create a Payment Link
description: "Pay by Link is an easy and fast way to securely sell products or receive\ndonations online. This solution is ideal for distributing the same\npayment link to multiple customers. \n\nLinks for making purchases are referred to as fixed-price links, and\nlinks for making donations are referred to as customer-set price links.\n"
operationId: createPaymentLink
x-devcenter-metaData:
categoryTag: Pay_By_Link
developerGuides: https://developer.cybersource.com/docs/cybs/en-us/paybylink/developer/all/rest/paybylink/paybylink-intro.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: createPaymentLinkRequest
in: body
required: true
schema:
type: object
required:
- processingInformation
- purchaseInformation
- 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.
'
processingInformation:
type: object
required:
- linkType
description: Contains processing information, such as the type and collection details.
properties:
linkType:
type: string
description: "linkType defines what type of link you want to create.\n\nPossible Values:\n - `PURCHASE`\n - `DONATION`\n"
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
purchaseInformation:
type: object
required:
- purchaseNumber
description: Contains link specific detail.
properties:
purchaseNumber:
type: string
maxLength: 50
description: The purchase number
orderInformation:
type: object
required:
- amountDetails
- lineItems
description: Contains all of the order-related fields, such as the amount and line item details.
properties:
amountDetails:
type: object
required:
- currency
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.
'
maxAmount:
type: string
description: Maximum custom amount allowed for Donation. The customer cannot enter more than maxAmount on payment checkout page.
minAmount:
type: string
description: Minimum custom amount allowed for Donation. The customer cannot enter less than minAmount on payment checkout page. Required for DONATION links.
lineItems:
type: array
description: List of the line items from the order.
maxItems: 30
items:
type: object
required:
- productName
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)
'
productDescription:
maxLength: 2000
type: string
description: Brief description of item.
discountAmount:
type: string
maxLength: 13
description: 'Discount amount applied to the item. Maximum of 2 decimal places. You may provide either discountAmount or discountPercent (not both).
If both are present, their values must be consistent. Otherwise, a validation error will be returned.
'
example: '10.00'
discountPercent:
type: string
maxLength: 6
description: 'Discount rate applied to the item. Maximum of 3 decimal places. You may provide either discountAmount or discountPercent (not both).
If both are present, their values must be consistent; otherwise, a validation error will be returned.
Example: 5.25 (=5.25%)
'
example: '5.25'
taxAmount:
type: string
maxLength: 15
description: 'Tax amount applied to the item. This value cannot be negative. Maximum of 2 decimal places. The tax amount and the offer amount must
be in the same currency. The tax amount field is additive. If taxAmount is provided but taxRate is not, the taxRate will be calculated.
'
example: '10.50'
taxRate:
type: string
maxLength: 7
description: 'Tax rate applied to the item. Valid range: 1.001% to 99.999%. Maximum of 3 decimal places.
If a taxRate is provided but taxAmount is missing or incorrect, the taxAmount based on the given taxRate will be overwritten.
Example: 21.00 (=21.00%)
'
example: '21.00'
example:
clientReferenceInformation:
partner:
developerId: '3435'
solutionId: '83745'
processingInformation:
linkType: PURCHASE
requestPhone: false
requestShipping: false
purchaseInformation:
purchaseNumber: '23412'
orderInformation:
amountDetails:
totalAmount: '12.05'
currency: USD
minAmount: '1'
lineItems:
- productName: First line item's name
productDescription: First line item's description
unitPrice: '12.05'
quantity: '10'
responses:
'201':
description: Created.
schema:
title: pblPaymentLinksPost201Response
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.'
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 purchase or donation link.
Possible values:
- ACTIVE
- INACTIVE
'
processingInformation:
type: object
required:
- linkType
description: Contains processing information, such as the type and collection details.
properties:
linkType:
type: string
description: "linkType defines what type of link you want to create.\n\nPossible Values:\n - `PURCHASE`\n - `DONATION`\n"
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
purchaseInformation:
type: object
description: Contains link specific detail.
properties:
purchaseNumber:
type: string
maxLength: 50
description: The purchase number
createdDate:
type: string
x-example: '2018-08-11T22:47:57Z'
description: 'Date and time (UTC) the invoice was created.
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.
'
paymentLink:
type: string
description: Returns the link to a purchase or donation link when the status is `ACTIVE`.
orderInformation:
type: object
description: Contains all of the order-related fields, such as the amount and line item details.
properties:
amountDetails:
type: object
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.
'
maxAmount:
type: string
description: Maximum custom amount allowed for Donation. The customer cannot enter more than maxAmount on payment checkout page.
minAmount:
type: string
description: Minimum custom amount allowed for Donation. The customer cannot enter less than minAmount on payment checkout page. Required for DONATION links.
lineItems:
type: array
description: List of the line items from the order.
maxItems: 30
items:
type: object
required:
- productName
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)
'
productDescription:
maxLength: 2000
type: string
description: Brief description of item.
discountAmount:
type: string
maxLength: 13
description: 'Discount amount applied to the item. Maximum of 2 decimal places. You may provide either discountAmount or discountPercent (not both).
If both are present, their values must be consistent. Otherwise, a validation error will be returned.
'
example: '10.00'
discountPercent:
type: string
maxLength: 6
description: 'Discount rate applied to the item. Maximum of 3 decimal places. You may provide either discountAmount or discountPercent (not both).
If both are present, their values must be consistent; otherwise, a validation error will be returned.
Example: 5.25 (=5.25%)
'
example: '5.25'
taxAmount:
type: string
maxLength: 15
description: 'Tax amount applied to the item. This value cannot be negative. Maximum of 2 decimal places. The tax amount and the offer amount must
be in the same currency. The tax amount field is additive. If taxAmount is provided but taxRate is not, the taxRate will be calculated.
'
example: '10.50'
taxRate:
type: string
maxLength: 7
description: 'Tax rate applied to the item. Valid range: 1.001% to 99.999%. Maximum of 3 decimal places.
If a taxRate is provided but taxAmount is missing or incorrect, the taxAmount based on the given taxRate will be overwritten.
Example: 21.00 (=21.00%)
'
example: '21.00'
example:
_links:
self:
href: /ipl/v2/payment-links/98753
method: GET
update:
href: /ipl/v2/payment-links/98753
method: PATCH
id: '98753'
submitTimeUtc: '2019-06-28T19:48:06Z'
status: ACTIVE
processingInformation:
linkType: PURCHASE
requestPhone: false
requestShipping: false
purchaseInformation:
purchaseNumber: '23412'
createdDate: '2018-08-11T22:47:57Z'
paymentLink: https://pay.cybersource.com/ip
# --- truncated at 32 KB (134 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cybersource/refs/heads/main/openapi/cybersource-payment-links-api-openapi.yml