A payout enables an originator to send funds on behalf of itself, merchants, or customers to credit card accounts using an Original Credit Transaction (OCT). An originator is a merchant, government entity, or corporation with a merchant account from an acquiring bank.
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 Push Funds API
host: apitest.cybersource.com
basePath: /
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/hal+json;charset=utf-8
tags:
- name: Push Funds
description: 'A payout enables an originator to send funds on behalf of itself, merchants, or customers to credit card
accounts using an Original Credit Transaction (OCT). An originator is a merchant, government entity, or
corporation with a merchant account from an acquiring bank.
'
paths:
/pts/v1/push-funds-transfer:
post:
summary: Process a Push Funds Transfer
description: 'Receive funds using an Original Credit Transaction (OCT).
'
tags:
- Push Funds
operationId: createPushFundsTransfer
x-devcenter-metaData:
categoryTag: Payouts
firstLevelApiLifeCycle: hidden
secondLevelApiLifeCycle: hidden
apiLifeCycle: hidden
developerGuides: https://developer.cybersource.com/api/developer-guides/dita-payouts/Introduction.html
isMLEsupported: true
mleForRequest: optional
parameters:
- name: pushFundsRequest
in: body
required: true
schema:
type: object
required:
- orderInformation
properties:
aggregatorInformation:
type: object
x-nullable: true
properties:
aggregatorId:
type: string
x-nullable: true
maxLength: 20
description: 'Value that identifies you as a payment aggregator. Get this value from the processor.
'
name:
type: string
x-nullable: true
maxLength: 37
description: 'Your payment aggregator business name. This field is conditionally required when aggregator id is present.
'
independentSalesOrganizationID:
type: string
x-nullable: true
maxLength: 11
description: 'Independent sales organization ID.
This field is only used for Mastercard transactions submitted through PPGS.
'
subMerchant:
type: object
x-nullable: true
properties:
id:
type: string
maxLength: 20
x-nullable: true
description: 'The ID you assigned to your sub-merchant.
'
streetAddress:
type: string
maxLength: 150
description: Acquirer street name.
city:
type: string
maxLength: 100
description: Acquirer city.
state:
type: string
maxLength: 10
description: Acquirer state.
postalCode:
type: string
maxLength: 20
description: Acquirer postal code.
country:
type: string
maxLength: 10
description: Acquirer country.
clientReferenceInformation:
type: object
x-nullable: true
properties:
code:
type: string
maxLength: 50
x-nullable: true
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.
'
applicationName:
type: string
maxLength: 50
x-nullable: true
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
maxLength: 50
x-nullable: true
description: 'Version of the CyberSource application or integration used for a transaction.
'
applicationUser:
type: string
maxLength: 60
x-nullable: true
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.
'
orderInformation:
type: object
required:
- amountDetails
properties:
amountDetails:
type: object
required:
- totalAmount
- currency
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. CyberSource truncates the amount to the correct number of decimal places.
'
currency:
type: string
pattern: ^(\s{0,3}|.{3})$
description: 'Use a 3-character alpha currency code for currency of the funds transfer.
ISO standard currencies: http://apps.cybersource.com/library/documentation/sbc/quickref/currencies.pdf
Currency must be supported by the processor.
'
sourceCurrency:
type: string
pattern: ^(\s{0,3}|.{3})$
x-nullable: true
description: 'Use a 3-character alpha currency code for source currency of the funds transfer. Supported for card and bank account based cross border funds transfers.
ISO standard currencies: http://apps.cybersource.com/library/documentation/sbc/quickref/currencies.pdf
'
destinationCurrency:
type: string
pattern: ^(\s{0,3}|.{3})$
x-nullable: true
description: 'Use a 3-character alpha currency code for destination currency of the funds transfer. Supported for card and bank account based cross border funds transfers.
ISO standard currencies: http://apps.cybersource.com/library/documentation/sbc/quickref/currencies.pdf
'
surcharge:
type: object
properties:
amount:
type: string
maxLength: 15
x-nullable: true
description: "The surcharge amount is included in the total transaction amount but is passed in a separate field to the issuer and acquirer for tracking. \nThe issuer can provide information about the surcharge amount to the customer. \n\nIf the amount is positive, then it is a debit for the customer. \n\nIf the amount is negative, then it is a credit for the customer.\n"
processingInformation:
type: object
x-nullable: true
properties:
businessApplicationId:
type: string
x-nullable: true
pattern: ^(\s{0,2}|.{2})$
description: "Money Transfer (MT)\n- `AA`: Account to Account\n- `BI`: Bank-Initiated Money Transfer\n- `CD`: Cash Deposit\n- `FT`: Funds Transfer\n- `TU`: Prepaid Card Loan\n- `WT`: Wallet Transfer-Staged Digital Wallet (SDW) Transfer\n- `PP`: P2P Money Transfer\n\nFunds Disbursement (FD)\n- `BB`: Business-to-business Supplier Payments\n-\t`BP`: Non-Card Bill Pay \n-\t`CP`: Credit Card Bill Pay\n-\t`FD`: General Funds Disbursements\n-\t`GD`: Government Disbursements and Government Initiated Tax Refunds\n-\t`GP`: Gambling/Gaming Payouts (other than online gaming)\n-\t`LO`: Loyalty Payments\n-\t`MD`: Merchant Settlement\n-\t`MI`: Faster Refunds\n-\t`OG`: Online Gambling Payouts\n-\t`PD`: Payroll and Pension Disbursements\n-\t`RP`: Request-to-Pay Service\n"
payoutsOptions:
type: object
properties:
sourceCurrency:
type: string
pattern: ^(\s{0,3}|.{3})$
x-nullable: true
description: 'Use a 3-character alpha currency code for source currency of the funds transfer.
Required if sending processingInformation.payoutsOptions.sourceAmount.
ISO standard currencies: http://apps.cybersource.com/library/documentation/sbc/quickref/currencies.pdf
'
destinationCurrency:
type: string
pattern: ^(\s{0,3}|.{3})$
x-nullable: true
description: 'Use a 3-character alpha currency code for destination currency of the funds transfer.
Yellow Pepper
Supported for cross border funds transfers.
ISO standard currencies: http://apps.cybersource.com/library/documentation/sbc/quickref/currencies.pdf
'
sourceAmount:
type: string
maxLength: 12
x-nullable: true
description: 'Source Amount is required in certain markets to identify the transaction amount entered in the sender''s currency code prior to FX conversion by the originating entity.
Format:
Minimum Value: 0
Maximum value: 999999999.99
Allowed fractional digits: 2
'
retrievalReferenceNumber:
type: string
maxLength: 24
x-nullable: true
description: 'Unique reference number returned by the processor that identifies the transaction at the network.
'
accountFundingReferenceId:
type: string
maxLength: 40
x-nullable: true
description: 'Visa (maxLength of 15) or MasterCard (maxLength of 40) generated transaction identifier (TID) that is unique for each original authorization and financial request.
'
feeProgramId:
type: string
x-nullable: true
pattern: ^(\s{0,3}|[a-zA-Z0-9]{3})$
description: 'Fee Program Indicator. This field identifies the interchange fee program applicable to each financial transaction. Fee program indicator (FPI) values correspond to the fee descriptor and rate for each existing fee program.
'
networkPartnerId:
type: string
x-nullable: true
maxLength: 8
description: 'Merchant payment gateway ID that is assigned by Mastercard and is provided by the acquirer when a registered merchant payment gateway service provider is involved in the transaction.
This field is supported for Visa Platform Connect, Chase Paymentech Salem.
'
processingCode:
type: string
x-nullable: true
pattern: ^(\s{0,4}|\d{4})$
description: 'This field contains coding that identifies (1) the customer transaction type and (2) the customer account types affected by the transaction.
Default: 5402 (Original Credit Transaction)
Contains codes that combined with some other fields such as the BAI (Business Application Id) identify some unique use cases. For Sales Tax rebates this field should be populated with the value 5120 (Value-added tax/Sales Tax) along with the businessApplicationId field set to the value ''FD'' which indicates this push funds transfer is being conducted in order to facilitate a sales tax refund.
'
sharingGroupCode:
type: string
x-nullable: true
maxLength: 16
description: 'This U.S.-only field is optionally used by PIN Debit Gateway Service participants (merchants and acquirers) to specify the network access priority. VisaNet checks to determine if there are issuer routing preferences for a network specified by the sharing group code. If an issuer preference exists for one of the specified debit networks, VisaNet makes a routing selection based on issuer preference. If an preference exists for multiple specified debit networks, or if no issuer preference exists, VisaNet makes a selection based on acquirer routing priorities.
Valid Values:
ACCEL_EXCHANGE_E
CU24_C
INTERLINK_G
MAESTRO_8
NYCE_Y
NYCE_F
PULSE_S
PULSE_L
PULSE_H
STAR_N
STAR_W
STAR_Z
STAR_Q
STAR_M
VISA_V
'
purposeOfPayment:
type: string
x-nullable: true
maxLength: 12
description: 'This will send purpose of funds code for original credit transactions (OCTs).
'
reconciliationId:
type: string
maxLength: 60
description: Transaction's reference number.
accountVerificationCode:
type: array
x-nullable: true
items:
type: string
description: 'Account verification code will inform what Payment Account Verification should be performed. With this array of codes, a merchant can choose à la carte what verifications to run. This field is optional, and the default is 1 if it is not passed in. This means that a full validation of the fields will be performed.
Valid verification codes:
- `1` = Full Account Verification (Card Account, CVN, CAVV, TAVV, Address, Name, eMail, Phone, Identity)
- `2` = Card Account Verification
- `3` = Address Verification
- `4` = Card Authentication Method (CAM) (Cryptogram)
- `5` = Cardholder Authentication Verification (CAVV)
- `6` = Cardholder Identity Verification
- `7` = CVV2 Verification
- `8` = eMail Verification
- `9` = Name Verification
- `10` = Phone Verification
'
recipientInformation:
type: object
properties:
paymentInformation:
type: object
properties:
card:
type: object
properties:
type:
type: string
pattern: ^(\s{0,3}|.{3})$
x-nullable: true
description: '- `001`: Visa
- `002`: Mastercard, Eurocard, which is a European regional brand of Mastercard.
- `033`: Visa Electron
- `024`: Maestro
- `042`: Maestro International
'
securityCode:
type: string
maxLength: 4
x-nullable: true
description: '4-digit value that indicates the cardCvv2Value. Values can be 0-9.
'
number:
type: string
maxLength: 20
x-nullable: true
description: 'The customer''s payment card number, also known as the Primary Account Number (PAN).
Conditional: this field is required if not using tokens.
'
expirationMonth:
type: string
maxLength: 2
x-nullable: true
description: 'Two-digit month in which the payment card expires.
Format: MM.
Valid values: 01 through 12. Leading 0 is required.
'
expirationYear:
type: string
maxLength: 4
x-nullable: true
description: 'Four-digit year in which the payment card expires.
Format: YYYY.
'
customer:
type: object
properties:
id:
type: string
x-nullable: true
maxLength: 32
description: 'Unique identifier for the Customer token used in the transaction. When you include this value in your request, many of the fields that are normally required for an authorization or credit become optional.
'
paymentInstrument:
type: object
properties:
id:
type: string
x-nullable: true
maxLength: 32
description: 'Unique identifier for the Payment Instrument token used in the transaction. When you include this value in your request, many of the fields that are normally required for an authorization or credit become optional.
'
instrumentIdentifier:
type: object
properties:
id:
type: string
x-nullable: true
maxLength: 32
description: 'Unique identifier for the Instrument Identifier token used in the transaction. When you include this value in your request, many of the fields that can be supplied for an authorization or credit become optional.
'
address1:
type: string
maxLength: 50
x-nullable: true
description: 'First line of the recipient''s address.
Required for card payments
'
address2:
type: string
maxLength: 50
x-nullable: true
description: 'Second line of the recipient''s address
'
locality:
type: string
maxLength: 25
x-nullable: true
description: 'Recipient city.
'
postalCode:
type: string
x-nullable: true
maxLength: 10
description: "Recipient postal code. \n\nFor USA, this must be a valid value of 5 digits or 5 digits hyphen 4 digits, for example '63368', '63368-5555'. For other regions, this can be alphanumeric, length 1-10.\n\nMandatory for card payments.\n"
administrativeArea:
type: string
maxLength: 3
x-nullable: true
description: 'The recipient''s province, state or territory. Conditional, required if recipient''s country is USA or CAN. Must be an ISO 3166-2 uppercase alpha 2 or 3 character country subdivision code. For example, Missouri is MO.
See https://developer.cybersource.com/library/documentation/sbc/quickref/states_and_provinces.pdf
Required for card payments.
'
country:
type: string
pattern: ^(\s{0,2}|.{2})$
x-nullable: true
description: 'Recipient country code. Use the ISO Standard Alpha Country Codes.
https://developer.cybersource.com/library/documentation/sbc/quickref/countries_alpha_list.pdf
'
firstName:
type: string
maxLength: 40
x-nullable: true
description: 'First name of recipient.
'
middleName:
type: string
maxLength: 40
x-nullable: true
description: 'Sender''s middle name. This field is a passthrough, which means that CyberSource does not verify the value or modify it in any way before sending it to the processor. If the field is not required for the transaction, CyberSource does not forward it to the processor.
'
lastName:
type: string
maxLength: 40
x-nullable: true
description: 'Last name of recipient.
'
phoneNumber:
type: string
x-nullable: true
maxLength: 20
description: 'Customer''s phone number.
It is recommended that you include the country code when the order is from outside the U.S.
'
email:
type: string
x-nullable: true
maxLength: 255
description: 'Customer''s email address, including the full domain name.
'
personalIdentification:
type: object
x-nullable: true
properties:
id:
type: string
x-nullable: true
maxLength: 80
description: 'The ID number/value.
Processor(35)
'
type:
type: string
x-nullable: true
maxLength: 4
description: "This tag will contain the type of sender identification. The valid values are:\n-\t`BTHD`: (Date of birth)\n-\t`CUID`: (Customer identification (unspecified))\n-\t`NTID`: (National identification)\n-\t`PASN`: (Passport number)\n-\t`DRLN`: (Driver license)\n-\t`TXIN`: (Tax identification)\n-\t`CPNY`: (Company registration number)\n-\t`PRXY`: (Proxy identification)\n-\t`SSNB`: (Social security number)\n-\t`ARNB`: (Alien registration number)\n-\t`LAWE`: (Law enforcement identification)\n-\t`MILI`: (Military identification)\n-\t`TRVL`: (Travel identification (non-passport))\n-\t`EMAL`: (Email)\n-\t`PHON`: (Phone number)\n"
issuingCountry:
type: string
x-nullable: true
pattern: ^(\s{0,2}|.{2})$
description: 'Issuing country of the identification.
The field format should be a 2 character ISO 3166-1 alpha-2 country code.
'
personalIdType:
type: string
x-nullable: true
maxLength: 1
description: "This tag will denote whether the tax ID is a business or individual tax ID when personal ID Type contains the value of TXIN (Tax identification).\n\nThe valid values are: \n- `B` (Business)\n- `I` (Individual)\n"
buildingNumber:
type: string
x-nullable: true
maxLength: 255
description: 'Building number in the street address.
For example, if the street address is: Rua da Quitanda 187 then the building number is 187.
Applicable to domestic Colombia transactions only.
'
streetName:
type: string
x-nullable: true
maxLength: 99
description: 'This field contains the street name of the recipient''s address.
Applicable to domestic Colombia transactions only.
'
type:
type: string
x-nullable: true
maxLength: 1
description: '`B` for Business or `I` for individual.
'
senderInformation:
type: object
properties:
name:
type: string
maxLength: 30
x-nullable: true
description: 'Name of sender.
Funds Disbursement
This value is the name of the originator sending the funds disbursement.
Government entities should use this field
'
email:
type: string
maxLength: 255
x-nullable: true
description: 'Customer''s email address, including the full domain name.
'
firstName:
type: string
maxLength: 40
x-nullable: true
description: 'This field contains the first name of the entity funding the transaction
Mandatory for card payments
'
lastName:
type: string
maxLength: 40
x-nullable: true
description: 'This field contains the last name of the entity funding the transaction
Mandatory for card payments
'
middleName:
type: string
maxLength: 40
x-nullable: true
description: 'This field contains the middle name of the entity funding the transaction
'
postalCode:
type: string
maxLength: 10
x-nullable: true
description: 'Sender''s postal code. For USA, this must be a valid value of 5 digits or 5 digits hyphen 4 digits, for example ''63368'', ''63368-5555''. For other regions, this can be alphanumeric, length 1-10.
Required for FDCCompass.
'
buildingNumber:
type: string
maxLength: 255
x-nullable: true
description: 'Building number in the street address.
For example, if the street address is: Rua da Quitanda 187 then the building number is 187.
Applicable to domestic Colombia transactions only.
'
streetName:
type: string
x-nullable: true
maxLength: 99
description: 'This field contains the street name of the recipient''s address.
Applicable to domestic Colombia transactions only.
'
address1:
type: string
maxLength: 60
x-nullable: true
description: 'Street address of sender.
Funds Disbursement
This value is the address of the originator sending the funds disbursement.
Required for card transactions
'
address2:
type: string
maxLength: 60
x-nullable: true
description: "Used for additional address information. For example: Attention: Accounts Payable \nOptional field.\n"
locality:
type: string
maxLength: 25
x-nullable: true
description: 'The sender''s city
Mandatory for card payments
'
administrativeArea:
type: string
maxLength: 3
x-nullable: true
description: 'Sender''s state. Use the State, Province, and Territory Codes for the United States and Canada.The sender''s province, state or territory. Conditional, required if sender''s country is USA or CAN. Must be uppercase alpha 2 or 3 character country subdivision code.
See https://developer.cybersource.com/library/documentation/sbc/quickref/states_and_provinces.pdf
Mandatory for card payments
'
country:
type: string
pattern: ^(\s{0,2}|.{2})$
x-nullable: true
description: 'Sender''s country code. Use ISO Standard Alpha Country Codes.
https://developer.cybersource.com/library/documentation/sbc/quickref/countries_alpha_list.pdf
'
dateOfBirth:
type: string
x-nullable: true
pattern: ^(\s{0,8}|.{8})$
description: 'Sender''s date of birth in YYYYMMDD format.
'
phoneNumber:
type: string
x-nullable: true
maxLength: 20
description: 'Customer''s phone number.
It is recommended that you include the country code when the order is from outside the U.S.
'
paymentInformation:
type: object
properties:
card:
type: object
properties:
type:
type: string
pattern: ^(\s{0,3}|.{3})$
x-nullable: true
description: "Three-digit value that indicates the card type.\n\nIMPORTANT It is strongly recommended that you include the card type field in request messages even if it is optional for your processor and card type. Omitting the card type can cause the transaction to be processed with the wrong card type.\n\nPossible values:\n-\t`001`: Visa. For card-present transactions on all processors except SIX, the Visa Electron card type is processed the same way that the Visa debit card is processed. Use card type value 001 for Visa Electron.\n-\t`002`: Mastercard, Eurocard[^1], which is a European regional brand of Mastercard.\n-\t`033`: Visa Electron\n-\t`024`: Maestro\n-\t`042`: Maestro International\n"
securityCode:
type: string
x-nullable: true
pattern: ^(\s{0,3}|.{3})$
description: '3-digit value that indicates the card Cvv2Value. Values can be 0-9.
# --- truncated at 32 KB (96 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cybersource/refs/heads/main/openapi/cybersource-push-funds-api-openapi.yml