CyberSource billingAgreements API
A billingAgreement is a stand-alone transaction that is not linked to any previous transactions. It takes money from your merchant bank account and returns it to the customer.
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 billingAgreements API
host: apitest.cybersource.com
basePath: /
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/hal+json;charset=utf-8
tags:
- name: billingAgreements
description: 'A billingAgreement is a stand-alone transaction that is not linked to any previous transactions. It takes money from
your merchant bank account and returns it to the customer.
'
paths:
/pts/v2/billing-agreements:
post:
summary: Create a Billing Agreement
description: "#### Standing Instruction:\nStanding Instruction with or without Token. Transaction amount in case First payment is coming along with registration. Only 2 decimal places allowed\n\n#### Create Mandate:\nYou can create a mandate through the direct debit mandate flow.\nPossible create mandate status values:\n - Pending—the create mandate request was successfully processed.\n - Failed—the create mandate request was not accepted.\n\n#### Import Mandate:\nIn the Bacs scheme, a mandate is created with a status of active. Direct debit collections can be made against it immediately.\nYou can import a mandate to the CyberSource database when:\n - You have existing customers with signed, active mandates\n - You manage mandates outside of CyberSource.\n\nWhen you import an existing mandate to the CyberSource database, provide a unique value for the mandate ID or the request results in an error.\nIf an import mandate request is not accepted, the import mandate status value is failed.\n"
tags:
- billingAgreements
operationId: billingAgreementsRegistration
x-devcenter-metaData:
categoryTag: Payments
developerGuides: https://developer.cybersource.com/api/developer-guides/dita-payments/GettingStarted.html
isMLEsupported: true
mleForRequest: optional
parameters:
- name: createBillingAgreement
in: body
required: true
schema:
type: object
properties:
agreementInformation:
type: object
properties:
id:
type: string
maxLength: 50
description: 'Identifier for the mandate.
#### SEPA/BACS
Required for mandates services
'
dateSigned:
type: string
description: 'Date the mandate has been signed. Format YYYYMMdd
#### SEPA/BACS
Required for Import Mandate
'
maxLength: 8
type:
type: string
description: "Identifies the type of schedule as either recurring, one-off, split or usage. \nPossible values:\n- recurring\n- oneoff\n- split\n- usage"
maxLength: 25
frequency:
type: string
description: "Regularity with which the event occurs. \nPossible values:\n- annual\n- monthly\n- quarterly\n- semiannual\n- weekly\n- daily\n- adhoc\n- intraday\n- fortnightly"
maxLength: 25
occurrencesPerPeriod:
type: integer
description: Number of occurrences during the specified period.
startDate:
type: string
description: Start date of the schedule. Format YYYYMMdd
maxLength: 8
endDate:
type: string
description: End date of the schedule. Format YYYYMMdd
maxLength: 8
clientReferenceInformation:
type: object
properties:
code:
type: string
maxLength: 51
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
#### SEPA/BACS
Required for mandates services
#### Paypal
Required for billing agreements
**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.
'
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.
'
pausedRequestId:
type: string
maxLength: 26
description: 'Used to resume a transaction that was paused for an order modification rule to allow for payer authentication to complete. To resume and continue with the authorization/decision service flow, call the services and include the request id from the prior decision call.
'
transactionId:
type: string
maxLength: 30
description: 'Identifier that you assign to the transaction. Normally generated by a client server to identify a unique API request.
**Note** Use this field only if you want to support merchant-initiated reversal and void operations.
#### Used by
**Authorization, Authorization Reversal, Capture, Credit, and Void**
Optional field.
#### PIN Debit
For a PIN debit reversal, your request must include a request ID or a merchant transaction identifier.
Optional field for PIN debit purchase or credit requests.
'
comments:
type: string
description: Brief description of the order or any comment you wish to add to the order.
partner:
type: object
properties:
originalTransactionId:
type: string
maxLength: 32
description: 'Value that links the previous transaction to the current follow-on request. This value is assigned by the client
software that is installed on the POS terminal, which makes it available to the terminal''s software and to
CyberSource. Therefore, you can use this value to reconcile transactions between CyberSource and the terminal''s
software.
CyberSource does not forward this value to the processor. Instead, the value is forwarded to the CyberSource
reporting functionality.
This field is supported only on these processors:
- American Express Direct
- Credit Mutuel-CIC
- FDC Nashville Global
- OmniPay Direct
- SIX
Optional field.
'
developerId:
type: string
maxLength: 8
description: 'Identifier for the developer that helped integrate a partner solution to CyberSource.
Send this value in all requests that are sent through the partner solutions built by that developer.
CyberSource assigns the ID to the developer.
**Note** When you see a developer ID of 999 in reports, the developer ID that was submitted is incorrect.
'
solutionId:
type: string
maxLength: 8
description: 'Identifier for the partner that is integrated to CyberSource.
Send this value in all requests that are sent through the partner solution. CyberSource assigns the ID to the partner.
**Note** When you see a solutionId of 999 in reports, the solutionId that was submitted is incorrect.
'
thirdPartyCertificationNumber:
type: string
maxLength: 12
description: 'Value that identifies the application vendor and application version for a third party gateway.
CyberSource provides you with this value during testing and validation.
This field is supported only on CyberSource through VisaNet.
#### Used by
**Authorization, Authorization Reversal, Capture, Credit, Incremental Authorization, and Void**
Optional field.
#### PIN debit
Required field for PIN debit credit, PIN debit purchase, or PIN debit reversal request.
'
applicationName:
type: string
description: 'The name of the Connection Method client (such as Virtual Terminal or SOAP Toolkit API) that the merchant uses to send a transaction request to CyberSource.
'
applicationVersion:
type: string
description: 'Version of the CyberSource application or integration used for a transaction.
'
applicationUser:
type: string
description: 'The entity that is responsible for running the transaction and submitting the processing request to CyberSource. This could be a person, a system, or a connection method.
'
aggregatorInformation:
type: object
properties:
name:
type: string
maxLength: 37
description: 'Your payment aggregator business name.
**American Express Direct**\
The maximum length of the aggregator name depends on the length of the sub-merchant name. The combined length for both values must not exceed 36 characters.\
#### CyberSource through VisaNet
With American Express, the maximum length of the aggregator name depends on the length of the sub-merchant name. The combined length for both values must not exceed 36 characters. The value for this field does not map to the TC 33 capture file5.
**FDC Compass**\
This value must consist of uppercase characters.
'
subMerchant:
type: object
properties:
cardAcceptorId:
type: string
maxLength: 15
description: Unique identifier assigned by the payment card company to the sub-merchant.
id:
type: string
maxLength: 20
description: 'The ID you assigned to your sub-merchant.
CyberSource through VisaNet: For American Express transaction, the value for this field corresponds to the following data in the TC 33 capture file:
- Record: CP01 TCRB
- Position: 65-84
- Field: American Express Seller ID
For Mastercard transactions, the value for this field corresponds to the following data in the TC 33 capture file:
- Record: CP01 TCR6
- Position: 117-131
- Field: Sub-Merchant ID
FDC Compass: This value must consist of uppercase characters.
American Express Direct: String (20)
CyberSource through VisaNet with American Express: String (20)
CyberSource through VisaNet with Visa,Mastercard and Discover: String (15)
FDC Compass: String (20)
FDC Nashville Global: String (14)
'
name:
type: string
maxLength: 37
description: 'Sub-merchant''s business name.
#### American Express Direct
The maximum length of the sub-merchant name depends on the length of the aggregator name. The combined length for both values must not exceed 36 characters.
#### CyberSource through VisaNet
With American Express, the maximum length of the sub-merchant name depends on the length of the aggregator name. The combined length for both values must not exceed 36 characters. The value for this field does not map to the TC 33 capture file5.
#### FDC Compass
This value must consist of uppercase characters.
#### FDC Nashville Global
With Mastercard, the maximum length of the sub-merchant name depends on the length of the aggregator name:
- If aggregator name length is 1 through 3, maximum sub-merchant name length is 21.
- If aggregator name length is 4 through 7, maximum sub-merchant name length is 17.
- If aggregator name length is 8 through 12, maximum sub-merchant name length is 12.
'
address1:
type: string
maxLength: 38
description: 'First line of the sub-merchant''s street address.
#### CyberSource through VisaNet
The value for this field does not map to the TC 33 capture file5.
#### FDC Compass
This value must consist of uppercase characters.
'
locality:
type: string
maxLength: 21
description: 'Sub-merchant''s city.
#### CyberSource through VisaNet
The value for this field does not map to the TC 33 capture file5.
#### FDC Compass
This value must consist of uppercase characters.
'
administrativeArea:
type: string
maxLength: 50
description: 'Sub-merchant''s state or province.
#### CyberSource through VisaNet
The value for this field does not map to the TC 33 capture file5.
#### FDC Compass
This value must consist of uppercase characters.
'
region:
type: string
maxLength: 3
description: 'Sub-merchant''s region.
**Example**\
`NE` indicates that the sub-merchant is in the northeast region.
'
postalCode:
type: string
maxLength: 15
description: 'Partial postal code for the sub-merchant''s address.
#### CyberSource through VisaNet
The value for this field does not map to the TC 33 capture file5.
#### FDC Compass
This value must consist of uppercase characters.
'
country:
type: string
maxLength: 3
description: 'Sub-merchant''s country. Use the [ISO Standard Country Codes](https://developer.cybersource.com/library/documentation/sbc/quickref/countries_alpha_list.pdf).
#### CyberSource through VisaNet
The value for this field does not map to the TC 33 capture file.
#### FDC Compass
This value must consist of uppercase characters.
'
email:
type: string
maxLength: 40
description: "Sub-merchant's email address.\n\n**Maximum length for processors**\n\n - American Express Direct: 40\n - CyberSource through VisaNet: 40\n - FDC Compass: 40\n - FDC Nashville Global: 19\n\n#### CyberSource through VisaNet\nWith American Express, the value for this field corresponds to the following data in the TC 33 capture file:\n- Record: CP01 TCRB\n- Position: 25-64\n- Field: American Express Seller E-mail Address\n\n**Note** The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource. CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchant's acquirer, who uses this information to facilitate end-of-day clearing processing with payment card companies.\n"
phoneNumber:
type: string
maxLength: 20
description: "Sub-merchant's telephone number.\n\n**Maximum length for procesors**\n\n - American Express Direct: 20\n - CyberSource through VisaNet: 20\n - FDC Compass: 13\n - FDC Nashville Global: 10\n\n#### CyberSource through VisaNet\nWith American Express, the value for this field corresponds to the following data in the TC 33 capture file5:\n- Record: CP01 TCRB\n- Position: 5-24\n- Field: American Express Seller Telephone Number\n\n**FDC Compass**\\\nThis value must consist of uppercase characters. Use one of these recommended formats:\\\n`NNN-NNN-NNNN`\\\n`NNN-AAAAAAA`\n"
merchantCategoryCode:
type: number
maxLength: 20
x-nullable: true
consumerAuthenticationInformation:
type: object
properties:
authenticationTransactionContextId:
type: string
maxLength: 30
description: 'Payer authentication transaction identifier passed to link the validation and authorization calls.
'
cavv:
type: string
maxLength: 255
description: 'Unique identifier generated by the card-issuing bank for Visa, American Express, JCB, Diners Club, and
Discover transactions after the customer is authenticated. The value is in base64. When you
request the card authorization service, CyberSource automatically converts the value, not the field name,
to the format required by your payment processor.
'
transactionToken:
type: string
maxLength: 256
description: 'Web based token used to authenticate consumer with Rupay authentication provider.
'
xid:
type: string
description: 'Transaction identifier generated by CyberSource for successful enrollment or validation checks.
Use this value, which is in base64, to match an outgoing PAReq with an incoming PARes.
CyberSource forwards the XID with the card authorization service to these payment processors in these cases:
- Barclays
- Streamline (when the **ecommerceIndicator**`=spa`)
'
deviceInformation:
type: object
properties:
httpAcceptBrowserValue:
type: string
maxLength: 255
description: 'Value of the Accept header sent by the customer''s web browser.
**Note** If the customer''s browser provides a value, you must include it in your request.
'
ipAddress:
type: string
maxLength: 45
description: 'IP address of the customer.
#### Used by
**Authorization, Capture, and Credit**
Optional field.
'
userAgentBrowserValue:
type: string
maxLength: 255
description: 'Value of the User-Agent header sent by the customer''s web browser.
Note If the customer''s browser provides a value, you must include it in your request.
'
installmentInformation:
type: object
properties:
alertPreference:
type: string
maxLength: 5
description: 'Applicable only for SI. Required in case the authentication is initiated for SI registration.
Valid Values:
- `SMS`
- `EMAIL`
- `BOTH`
'
firstInstallmentDate:
type: string
maxLength: 6
description: 'Date of the first installment payment. Format: YYMMDD. When you do not include this field, CyberSource sends a string of six zeros (000000) to the processor.
This field is supported only for Crediario installment payments in Brazil on CyberSource through VisaNet.
The value for this field corresponds to the following data in the TC 33 capture file:
- Record: CP01 TCR9
- Position: 42-47
- Field: Date of First Installment
'
identifier:
type: string
maximum: 60
description: 'Standing Instruction/Installment identifier.
'
lastInstallmentDate:
type: string
maxLength: 8
description: 'End date of the SI transactions.
Cannot be later than card expiry date. Ideally this can be set to expiry date.
Required in case the authentication is initiated for SI registration.
'
maxAmount:
type: string
maxLength: 12
description: 'Maximum Amount for which SI can be initiated.
Required in case the authentication is initiated for SI registration.
'
minAmount:
type: string
maxLength: 12
description: 'Minimum Amount for which SI can be initiated.
Required in case the authentication is initiated for SI registration.
'
paymentType:
type: string
maxLength: 1
description: 'Payment plan for the installments.
This field is supported only for installment payments on Visa Platform Connect, RuPay and SPG-KSA seamless flow.
Possible values for a standing-instruction (SI) merchant-initiated transaction (MIT) with Diners Club or Mastercard in India or with an India-issued card:
- 1: SI with a fixed amount.
- 2: SI with a maximum amount.
- 3: Other kind of SI.
Possible values for a type of Installment transaction for on-soil transaction in Kingdom of Saudi Arabia
- 1: Registration or first transaction.
- 2: Subsequent transaction.
Possible values for other kinds of installment payments:
- 0 (default): Regular installment. This value is not allowed for airline transactions.
- 1: Installment payment with down payment.
- 2: Installment payment without down payment. This value is supported only for airline transactions.
- 3: Installment payment; down payment and boarding fee will follow. This value is supported only for airline transactions.
- 4: Down payment only; regular installment payment will follow.
- 5: Boarding fee only. This value is supported only for airline transactions.
- 6: SI de-registration on RuPay for the payer authentication seamless flow.
'
preferredDay:
type: string
maxLength: 2
description: 'Preferred date for initiating the SI transaction every month.
This field need not be sent in case the SI has to be initiated as and when required, e.g., topping up the wallet, etc.
'
sequence:
type: integer
maximum: 999
description: 'Installment number when making payments in installments. Used along with `totalCount` to track which payment is being processed.
For example, the second of 5 payments would be passed to CyberSource as `sequence` = 2 and `totalCount` = 5.
#### Chase Paymentech Solutions and FDC Compass
This field is optional because this value is required in the merchant descriptors.
#### CyberSource through VisaNet
When you do not include this field in a request for a Crediario installment payment, CyberSource sends a value of 0 to the processor.
For Crediario installment payments, the value for this field corresponds to the following data in the TC 33 capture file*:
- Record: CP01 TCR9
- Position: 38-40
- Field: Installment Payment Number
* The TC 33 Capture file contains information about the purchases and refunds that a merchant submits to CyberSource. CyberSource through VisaNet creates the TC 33 Capture file at the end of the day and sends it to the merchant''s acquirer, who uses this information to facilitate end-of-day clearing processing with payment card companies.
'
merchantInformation:
type: object
properties:
merchantDescriptor:
type: object
properties:
postalCode:
type: string
maxLength: 14
description: 'Merchant''s postal code.
#### PIN debit
Postal code for your business location. This value might be displayed on the cardholder''s statement.
If your business is domiciled in the U.S., you can use a 5-digit or 9-digit postal code. A 9-digit postal code must follow this format:
[5 digits][dash][4 digits]
Example: `12345-6789`
If your business is domiciled in Canada, you can use a 6-digit or 9-digit postal code. A 6-digit postal code must follow this format:
[alpha][numeric][alpha][space]
[numeric][alpha][numeric]
Example: `A1B 2C3`
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.
**Note** This field is supported only for businesses located in the U.S. or Canada.
**Important** Mastercard requires a postal code for any country that uses postal codes.
You can provide the postal code in your account or you can include this field in your request.
Optional field for PIN debit credit or PIN debit purchase.
'
contact:
type: string
maxLength: 25
description: 'Contact information for the merchant.
**Note** These are the maximum data lengths for the following payment processors:
- FDCCompass (13)
- Paymentech (13)
'
locality:
type: string
maxLength: 30
description: 'Merchant''s City.
#### PIN debit
City for your business location. This value might be displayed on the cardholder''s statement.
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.
'
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.
'
categoryCode:
type: integer
maximum: 9999
description: 'The value for this field is a four-digit number that the payment card industry uses to classify
merchants into market segments. A payment card company assigned one or more of these values to your business when you started
accepting the payment card company''s cards. When you do not include this field in your request, CyberSource uses the value in your
CyberSource account.
#### CyberSource through VisaNet
The value for this field corresp
# --- truncated at 32 KB (335 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cybersource/refs/heads/main/openapi/cybersource-billingagreements-api-openapi.yml