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.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/cybersource-billingagreements-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.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 Billing Agreements API
servers:
- url: https://apitest.cybersource.com/
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
responses:
'201':
description: Successful response.
content:
application/hal+json;charset=utf-8:
schema:
title: ptsV2CreateBillingAgreementPost201Response
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.'
updateAgreement:
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.'
revokeAgreement:
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.'
status:
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
maxLength: 15
description: "The status of the billing agreement.\nPossible value is:\n - PENDING\n - REVOKED\n - ACTIVE\n - FAILED\n - EXPIRED\n - INACTIVE\n"
processorInformation:
type: object
properties:
approvalCode:
type: string
maxLength: 6
description: 'Authorization code. Returned only when the processor returns this value.
The length of this value depends on your processor.
Returned by authorization service.
#### PIN debit
Authorization code that is returned by the processor.
Returned by PIN debit credit.
#### Elavon Encrypted Account Number Program
The returned value is OFFLINE.
#### TSYS Acquiring Solutions
The returned value for a successful zero amount authorization is 000000.
'
responseCode:
type: string
maxLength: 10
description: 'For most processors, this is the error message sent directly from the bank. Returned only when the processor
returns this value.
**Important** Do not use this field to evaluate the result of the authorization.
#### SEPA/BACS
Response code from the processor. Possible values: 00000–99999. See Appendix C,
"Reason Codes and Processor Response
Codes," on page 42.
#### PIN debit
Response value that is returned by the processor or bank.
**Important** Do not use this field to evaluate the results of the transaction request.
Returned by PIN debit credit, PIN debit purchase, and PIN debit reversal.
#### AIBMS
If this value is `08`, you can accept the transaction if the customer provides you with identification.
#### Atos
This value is the response code sent from Atos and it might also include the response code from the bank.
Format: `aa,bb` with the two values separated by a comma and where:
- `aa` is the two-digit error message from Atos.
- `bb` is the optional two-digit error message from the bank.
#### Comercio Latino
This value is the status code and the error or response code received from the processor separated by a colon.
Format: [status code]:E[error code] or [status code]:R[response code]
Example `2:R06`
#### JCN Gateway
Processor-defined detail error code. The associated response category code is in the `processorInformation.responseCategoryCode` field.
String (3)
'
transactionId:
type: string
maxLength: 255
description: 'Transaction ID assigned by the processor.
'
responseDetails:
type: string
maxLength: 60
description: 'Response code indicating that creating the agreement failed
'
reasonCode:
type: string
maxLength: 5
description: 'Numeric value corresponding to the result of the request.
'
installmentInformation:
type: object
properties:
identifier:
type: string
maxLength: 100
description: 'Identifier
'
agreementInformation:
type: object
properties:
id:
type: string
maxLength: 50
description: 'Identifier for the mandate.
'
dateSigned:
type: string
description: Date the mandate has been signed. Format YYYYMMdd
maxLength: 8
dateCreated:
type: string
description: Date the mandate has been created. Format YYYYMMdd
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
encodedHtml:
type: string
description: Base64 encoded html string
encodedHtmlPopup:
type: string
description: Base64 encoded popup html string
url:
type: string
maxLength: 2048
description: 'URL for redirecting the customer for creating
the mandate.
'
clientReferenceInformation:
type: object
properties:
code:
type: string
maxLength: 50
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.
'
riskInformation:
type: object
properties:
processorResults:
type: object
properties:
riskScore:
type: string
maxLength: 25
description: 'Risk score returned by the processor. Possible
values of 0-10. A value of 10 indicates a high risk.
'
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.
'
example:
_links:
self:
href: GET
method: /pts/v2/billing-agreements
updateAgreement:
href: PATCH
method: /pts/v2/billing-agreements/6891011351636003303961
revokeAgreement:
href: PATCH
method: /pts/v2/billing-agreements/6891011351636003303961
status:
href: PATCH
method: /pts/v2/billing-agreements/6891011351636003303961
id: '6853506446826005503878'
installmentInformation:
identifier: '1000000000'
processorInformation:
approvalCode: '888888'
responseCode: '00'
transactionId: 2016011808153910011808153910TR
responseDetails: '00001'
reasonCode: '100'
status: SUCCESS
submitTimeUtc: '2023-05-29T08:57:25Z'
agreementInformation:
id: G8UD2OKG49UW
dateSigned: '20181109'
dateCreated: '20181009'
encodedHtml: PGh0bWw+DQo8Ym9keT4NCiANCjxwPjxiPlRoaXMgdGV4dCBpcyBib2xkPC9iPjwvcD4NCjxwPjxpPlRoaXMgdGV4dCBpcyBpdGFsaWM8L2k+PC9wPg0KPHA+VGhpcyBpczxzdWI+IHN1YnNjcmlwdDwvc3ViPiBhbmQgPHN1cD5zdXBlcnNjcmlwdDwvc3VwPjwvcD4NCiANCjwvYm9keT4NCjwvaHRtbD4NCg==
encodedHtmlPopup: PGh0bWw+DQo8Ym9keT4NCiANCjxwPjxiPlRoaXMgdGV4dCBpcyBib2xkPC9iPjwvcD4NCjxwPjxpPlRoaXMgdGV4dCBpcyBpdGFsaWM8L2k+PC9wPg0KPHA+VGhpcyBpczxzdWI+IHN1YnNjcmlwdDwvc3ViPiBhbmQgPHN1cD5zdXBlcnNjcmlwdDwvc3VwPjwvcD4NCiANCjwvYm9keT4NCjwvaHRtbD4NCg==
url: https://merchant.redirect.com/url.do?param_utf=%27%22%3C%3E%20%E6%B8%AC%E8%A9%A6%E6%B8%AC¶m_url=https%3A%2F%2Fwww.abc.com¶m_special=+@#%~_&sign=fdaa1df42b6260a10e2e3f1c0fc87862
clientReferenceInformation:
code: TC84170-1
riskInformation:
processorResults:
riskScore: '3'
reconciliationId: 39570715X3E1LBQA
'400':
description: Invalid request.
content:
application/hal+json;charset=utf-8:
schema:
title: ptsV2CreateBillingAgreementPost400Response
type: object
properties:
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
maxLength: 20
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"
reason:
type: string
description: "The reason of the status.\n\nPossible values:\n - MISSING_FIELD\n - INVALID_DATA\n - DUPLICATE_REQUEST\n - INVALID_MERCHANT_CONFIGURATION\n - PROCESSOR_UNAVAILABLE\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"
example:
id: '6981713080281234567890'
submitTimeUtc: '2023-11-28T14:12:01Z'
status: INVALID_REQUEST
reason: INVALID_DATA
message: One or more fields in the request contains invalid data.
details:
- field: clientReferenceInformation.code
reason: INVALID_DATA
'502':
description: Unexpected system error or system timeout.
content:
application/hal+json;charset=utf-8:
schema:
title: ptsV2CreateBillingAgreementPost502Response
type: object
properties:
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
maxLength: 20
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.
example:
id: '6981713080281234567890'
submitTimeUtc: '2023-11-28T14:12:01Z'
status: SERVER_ERROR
reason: SYSTEM_ERROR
message: General system failure.
x-example:
example0:
summary: Standing Instruction Completion Amount = 0
sample-name: Standing Instruction Completion
value:
deviceInformation:
httpAcceptBrowserValue: http
userAgentBrowserValue: safari
ipAddress: 10.10.10.10
consumerAuthenticationInformation:
authenticationTransactionContextId: '100000000000000000000000025253'
transactionToken: AxjzbwSTcz9aHyOIL490/949UafAxfvksgAxHXa2/+xcVZ0CtA+AbkvF
processingInformation:
commerceIndicator: rpy
aggregatorInformation:
subMerchant:
name: rupay
name: aggregatorname
orderInformation:
amountDetails:
totalAmount: '00.00'
currency: INR
paymentInformation:
card:
expirationYear: '2031'
number: '5082302886091'
securityCode: '123'
expirationMonth: '12'
type: '061'
installmentInformation:
paymentType: '1'
example1:
summary: Standing Instruction Completion Tokenized
sample-name: Standing Instruction Completion
value:
deviceInformation:
httpAcceptBrowserValue: http
userAgentBrowserValue: safari
ipAddress: 10.10.10.10
consumerAuthenticationInformation:
authenticationTransactionContextId: '100000000000000000000000025253'
transactionToken: AxjzbwSTcz9aHyOIL490/949UafAxfvksgAxHXa2/+xcVZ0CtA+AbkvF
processingInformation:
commerceIndicator: rpy
actionList:
- BILLING_AGREEMENT_CREATE
aggregatorInformation:
subMerchant:
name: rupay
name: aggregatorname
orderInformation:
amountDetails:
totalAmount: '100.00'
currency: INR
paymentInformation:
tokenizedCard:
cryptogram: abcdefgh
expirationYear: '2031'
number: '5082794233463'
expirationMonth: '12'
type: '061'
transactionType: '1'
installmentInformation:
paymentType: '1'
example2:
summary: Redirectional Standing Instruction Completion Amount = 0
sample-name: S2S Standing Instruction Completion
value:
deviceInformation:
httpAcceptBrowserValue: http
userAgentBrowserValue: safari
ipAddress: 10.10.10.10
consumerAuthenticationInformation:
cavv: MTAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDI1MjM2
xid: OTE0OTE2MzI5MzE1MDUyOTU4Mjc=
processingInformation:
commerceIndicator: rpy
aggregatorInformation:
subMerchant:
name: rupay
name: aggregatorname
orderInformation:
amountDetails:
totalAmount: '00.00'
currency: INR
paymentInformation:
card:
expirationYear: '2026'
number: '50823043205909'
securityCode: '123'
expirationMonth: 08
type: '061'
installmentInformation:
paymentType: '1'
requestBody:
content:
application/json;charset=utf-8:
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
# --- truncated at 32 KB (355 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cybersource/refs/heads/main/openapi/cybersource-billingagreements-api-openapi.yml