CyberSource Pull Funds API
Cybersource Payouts Funds Transfer REST API for Account Funding Transaction (AFT)
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 Pull Funds API
host: apitest.cybersource.com
basePath: /
schemes:
- https
consumes:
- application/json;charset=utf-8
produces:
- application/hal+json;charset=utf-8
tags:
- name: Pull Funds
description: 'Cybersource Payouts Funds Transfer REST API for Account Funding Transaction (AFT)
'
paths:
/pts/v1/pull-funds-transfer:
post:
summary: Process a Pull Funds Transfer
description: 'Receive funds using an Account Funding Transaction (AFT).
'
tags:
- Pull Funds
operationId: createPullFundsTransfer
x-devcenter-metaData:
categoryTag: Payouts
developerGuides: https://developer.cybersource.com/docs/cybs/en-us/payouts/developer/visadirect/rest/payouts-dev/payouts-intro-intro.html
parameters:
- name: pullFundsRequest
in: body
required: true
schema:
type: object
properties:
clientReferenceInformation:
type: object
x-nullable: true
properties:
code:
type: string
x-nullable: true
maxLength: 50
description: 'Originator-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 that the originator 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
properties:
amountDetails:
type: object
required:
- totalAmount
- currency
properties:
totalAmount:
type: string
maxLength: 12
description: "The total amount of the funds transfer including all fees.\n\nThis value cannot be negative. \nYou can include a decimal point (.), but no other special characters.\n"
currency:
type: string
maxLength: 3
description: "Use a 3-character alpha currency code for currency of the sender.\n\nISO standard currencies: [http://apps.cybersource.com/library/documentation/sbc/quickref/currencies.pdf](http://apps.cybersource.com/library/documentation/sbc/quickref/currencies.pdf) \n\nCurrency must be supported by the processor.\n"
serviceFee:
type: string
maxLength: 8
x-nullable: true
description: 'When present, this field contains the sender''s surcharge as assessed by the originator. Values in this field must be in the same currency and format as defined in the amount field.
'
foreignExchangeFee:
type: string
maxLength: 12
x-nullable: true
description: 'When present, this field contains the sender''s foreign exchange markup fee (markup above the wholesale or VisaNet exchange rate as assessed by the originator). Values in this field must be in the same currency and format as defined in the amount field.
'
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"
isCryptoCurrencyPurchase:
type: string
x-nullable: true
maxLength: 5
description: 'This indicates that the funds transfer is for a crypto currency transaction.
Optional
Y/y, true
N/n, false
'
processingInformation:
type: object
required:
- businessApplicationId
properties:
commerceIndicator:
type: string
x-nullable: true
maxLength: 18
description: "Type of transaction. This field identifies the level of security used in an electronic commerce transaction over an open network (for example, the internet).\n\nValues for a Payouts transaction: \n`INTERNET`, `RECURRING`, `RECURRING_INTERNET`, `VBV_FAILURE`, `VBV_ATTEMPTED`, `VBV`, `SPA_FAILURE`, `SPA_ATTEMPTED`, `SPA` \n\nIf no value is entered this field will set a default value = `INTERNET`.\n"
fundingOptions:
type: object
x-nullable: true
properties:
initiator:
type: object
x-nullable: true
properties:
originatorInitiatedTransaction:
type: object
x-nullable: true
properties:
originalTransactionId:
type: string
maxLength: 15
x-nullable: true
description: "Contains a Visa-generated Transaction Identifier (TID) that is unique for each original authorization and financial request. The identifier links original messages to subsequent messages.\n\nConditional field. If the `processingInformation.fundingOptions.initiator.type`=`originator`, this field is mandatory. \n\n**Notes**: \n1. If an Pull Funds Transfer (AFT) transaction has a corresponding Push Funds Transfer (OCT) transaction, originators are strongly recommended to take the Transaction ID from the AFT and populate it into the OCT to link the two transactions together. \n2. Originators must link the Originator-Initiated Transaction with the original transaction using the Transaction Identifier that was generated for the original cardholder initiated transaction. However, for standing-instruction MITs (i.e., recurring), acquirers can use the Transaction Identifier generated for the previous transaction in the series to link the subsequent transactions.\n"
reason:
type: string
pattern: ^(\s{0,1}|.{1})$
x-nullable: true
description: 'Possible values:
- `1`: Resubmission
- `2`: Delayed charge
- `3`: Reauthorization for split shipment
- `4`: No show
- `5`: Account top up
Conditional: This field is not required for recurring transactions or when `processingInformation.fundingOptions.initiator.credentialStoredOnFile` = `True`. It is required for all other originator-initiated (MIT) transactions.
'
type:
type: string
maxLength: 10
x-nullable: true
description: 'This field indicates whether the transaction is a originator-initiated transaction or sender-initiated transaction.
Valid values:
- `sender`
- `originator`
Conditional field. If value in this field is `originator`, this field is mandatory for originator-initated transactions.
'
storedCredentialUsed:
type: boolean
x-nullable: true
description: 'Indicates to an issuing bank whether an originator-initiated transaction came from a card that was already stored on file.
Possible values:
- `True` = originator-initiated transaction came from a card that was already stored on file
- `False` = originator-initiated transaction came from a card that was not stored on file
Conditional for MITCOF transactions
'
credentialStoredOnFile:
type: boolean
x-nullable: true
description: "Flag that indicates whether the transaction is the first originator-initiated transaction in a series, which means that the customer initiated the previous transaction. \n\nPossible values:\n- `True`: First originator-initiated transaction\n- `False`: Not the first originator-initiated transaction\n\nConditional for MITCOF transactions\n"
recurringOptions:
type: object
x-nullable: true
properties:
firstRecurringPayment:
type: boolean
x-nullable: true
description: 'Indicates the transaction that is the first of a series of recurring payments.
- `True` = is first recurring payment
- `False` = is not first recurring payment
Conditional for MITCOF transactions
'
businessApplicationId:
type: string
pattern: ^(\s{0,2}|.{2})$
description: 'Payouts transaction type.
Possible Values:
- `AA` = Account to account
- `PP` = Person to person
- `TU` = Top-up for enhanced prepaid loads
- `WT` = Wallet transfer
- `BI` = Bank-Initiated
- `FT` = Funds Transfer
- `FD` = Funds Disbursement
- `MP` = Merchant Payment
- `PD` = Payroll Disbursement
- `LA` = Liquid Assets
'
purposeOfPayment:
type: string
x-nullable: true
maxLength: 12
description: "Visa Direct \nPurpose of payment is required in certain markets to clearly identify the purpose of the payment based on the standard values defined for respective market.\n"
payoutsOptions:
type: object
x-nullable: true
properties:
retrievalReferenceNumber:
type: string
x-nullable: true
maxLength: 12
description: "This field contains a number that is used with other data elements as a key to identify and track all messages related to a given cardholder transaction; that is, to a given transaction set.\n\nRecommended format: ydddhhnnnnnn \n\nPositions 1-4: The yddd equivalent of the date, where y = 0-9 and ddd = 001 – 366. \nPositions 5-12: A unique identification number generated by the merchant.\n"
languageCode:
type: string
x-nullable: true
maxLength: 3
description: 'Contains the ISO 639-2 defined language Code
'
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
x-nullable: true
properties:
administrativeArea:
type: string
maxLength: 3
x-nullable: true
description: "Recipient's state. Use the State, Province, and Territory Codes for the United States and Canada.\nValue must be an ISO Standard State Code: \nhttps://developer.cybersource.com/library/documentation/sbc/quickref/states_and_provinces.pdf\n"
postalCode:
type: string
maxLength: 10
x-nullable: true
description: 'Recipient''s postal code.
'
country:
type: string
pattern: ^(\s{0,2}|.{2})$
x-nullable: true
description: 'Recipient''s country code. Check that this field contains 2-character alpha ISO 3166-1 standard values.
'
personalIdentification:
type: object
x-nullable: true
properties:
issuingCountry:
type: string
maxLength: 2
x-nullable: true
description: 'Issuing country of the identification. The field format should be a 2 character ISO 3166-1 alpha-2 country code.
'
id:
type: string
maxLength: 35
x-nullable: true
description: 'This tag will contain an acquirer-populated id value associated with the API.
'
type:
type: string
pattern: ^(\s{0,4}|.{4})$
x-nullable: true
description: 'This tag will contain the type of recipient identification. The valid values are:
- `BTHD`: (Date of birth)
- `CUID`: (Customer identification (unspecified))
- `NTID`: (National identification)
- `PASN`: (Passport number)
- `DRLN`: (Driver license)
- `TXIN`: (Tax identification)
- `CPNY`: (Company registration number)
- `PRXY`: (Proxy identification)
- `SSNB`: (Social security number)
- `ARNB`: (Alien registration number)
- `LAWE`: (Law enforcement identification)
- `MILI`: (Military identification)
- `TRVL`: (Travel identification (non-passport))
- `EMAL`: (Email)
- `PHON`: (Phone number)
'
personalIdType:
type: string
pattern: ^(\s{0,1}|.{1})$
x-nullable: true
description: "This field denotes whether the Tax ID is a business or individual's Tax ID when idType contains the value of TXIN (Tax identification). \nThe valid values are: B (Business) I (Individual)\n"
firstName:
type: string
maxLength: 35
x-nullable: true
description: 'Recipient''s first name.
'
middleInitial:
type: string
maxLength: 1
x-nullable: true
description: 'Middle Initial of recipient.
This field is supported by FDC Compass.
'
middleName:
type: string
maxLength: 35
x-nullable: true
description: 'Recipient''s middle name. This field is a pass through,
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: 35
x-nullable: true
description: 'Recipient''s last name. Conditional field. If `recipientInformation.sameAsSender` = `false`, this field is mandatory.
'
address1:
type: string
maxLength: 60
x-nullable: true
description: 'Street address of recipient. This field is conditional: it is required if using neither a Customer nor Payment Instrument token.
'
address2:
type: string
maxLength: 60
x-nullable: true
description: 'Second line of the recipient''s address.
'
buildingNumber:
type: string
maxLength: 16
x-nullable: true
description: 'This field contains the house or the building number of the recipient address.
'
locality:
type: string
maxLength: 25
x-nullable: true
description: 'Recipient city.
'
identificationNumber:
type: string
maxLength: 35
x-nullable: true
description: "Government-issued identification number.\n\nConditional: This field is mandatory if the `processingInformation.businessApplicationId` is any of the following: \n- `AA`\n- `PP`\n- `TU`\n- `BI`\n- `WT`\n- `FT`\n- and country code = `BR`, `AR`, `CO`, `PE`, in `recipientInformation.countryCode` (Argentina, Brazil, Colombia, and Peru)\n"
type:
type: string
maxLength: 1
x-nullable: true
description: '`B` for Business or `I` for individual.
Conditional: If `recipientInformation.identificationNumber` is present, then this field is mandatory.
'
descriptor:
type: string
maxLength: 25
x-nullable: true
description: 'Recipient first name, this will be concatenated with the 4-digit originator abbreviation.
'
accountId:
type: string
maxLength: 50
x-nullable: true
description: 'Identifier for the recipient''s account.
'
accountType:
type: string
maxLength: 2
x-nullable: true
description: 'Identifies the recipient''s account type. This field is applicable for AFT transactions.
Valid values are:
- `00` Other
- `01` Routing transit number (RTN) and bank account
- `02` IBAN
- `03` Card account
- `04` Email
- `05` Phone number
- `06` Bank account number (BAN) and bank identification code (BIC)
- `07` Wallet ID
- `08` Social network ID
'
aliasName:
type: string
maxLength: 50
x-nullable: true
description: 'Account owner alias name.
'
countryOfBirth:
type: string
pattern: ^(\s{0,2}|.{2})$
x-nullable: true
description: 'Account Owner Country of Birth
'
dateOfBirth:
type: string
maxLength: 8
x-nullable: true
description: 'Recipient''s date of birth. Format: YYYYMMDD.
'
email:
type: string
maxLength: 150
x-nullable: true
description: 'Account Owner email address
'
nationality:
type: string
pattern: ^(\s{0,2}|.{2})$
x-nullable: true
description: 'Account Owner Nationality
'
occupation:
type: string
maxLength: 50
x-nullable: true
description: 'Account Owner Occupation
'
streetName:
type: string
maxLength: 35
x-nullable: true
description: 'This field contains the street name of the recipient''s address.
'
senderInformation:
type: object
properties:
postalCode:
type: string
maxLength: 10
x-nullable: true
description: 'Sender''s postal code. This field is conditional: it is required if using neither a Customer nor Payment Instrument token.
'
firstName:
type: string
maxLength: 35
x-nullable: true
description: 'First name of sender. This field is conditional: it is required if using neither a Customer nor Payment Instrument token.
'
middleInitial:
type: string
maxLength: 1
x-nullable: true
description: 'Middle Initial of sender
'
middleName:
type: string
maxLength: 35
x-nullable: true
description: 'This field contains the middle name of the entity funding the transaction.
'
lastName:
type: string
maxLength: 35
x-nullable: true
description: 'Last name of sender. This field is conditional: it is required if using neither a Customer nor Payment Instrument token.
'
address1:
type: string
maxLength: 60
x-nullable: true
description: 'Street address of sender. This field is conditional: it is required if using neither a Customer nor Payment Instrument token.
'
address2:
type: string
maxLength: 60
x-nullable: true
description: 'Second line of the sender''s address.
'
locality:
type: string
maxLength: 25
x-nullable: true
description: 'City of sender. This field is conditional: it is required if using neither a Customer nor Payment Instrument token.
'
administrativeArea:
type: string
maxLength: 2
x-nullable: true
description: "Sender's state. Use the **State, Province, and Territory Codes for the United States and Canada**. This field is conditional: it is required if in the United States or Canada, and transaction is using neither a Customer nor Payment Instrument token. \n\nValue must be an ISO Standard State Code: [https://developer.cybersource.com/library/documentation/sbc/quickref/states_and_provinces.pdf](https://developer.cybersource.com/library/documentation/sbc/quickref/states_and_provinces.pdf)\n"
country:
type: string
pattern: ^(\s{0,2}|.{2})$
x-nullable: true
description: 'Country of sender. Check that this field contains 2 character alpha ISO 3166-1 standard values. This field is conditional: it is required if using neither a Customer nor Payment Instrument token.
'
paymentInformation:
type: object
x-nullable: true
properties:
card:
type: object
x-nullable: true
properties:
type:
type: string
pattern: ^(\s{0,3}|.{3})$
x-nullable: true
description: 'Three-digit value that indicates the card type. Mandatory if not present in a token.
Possible values:
- `001`: Visa
- `002`: Mastercard, Eurocard, which is a European regional brand of Mastercard.
- `033`: Visa Electron
- `024`: Maestro
'
securityCode:
type: string
pattern: ^(\s{0,3}|.{3})$
x-nullable: true
description: '3-digit value that indicates the cardCvv2Value. Values can be 0-9.
'
number:
type: string
pattern: ^(\s{0,19}|.{13,19})$
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.
Conditional: this field is required if using neither a Customer nor Payment Instrument token.
'
expirationYear:
type: string
maxLength: 4
x-nullable: true
description: 'Four-digit year in which the payment card expires.
Format: `YYYY`.
Conditional: this field is required if using neither a Customer nor Payment Instrument token.
'
tokenizedCard:
type: object
x-nullable: true
properties:
cryptogram:
type: string
x-nullable: true
maxLength: 255
description: This field contains token cryptogram information
expirationMonth:
type: string
x-nullable: true
maxLength: 2
description: "One of two possible meanings:\n\nThe two-digit month in which a token expires.\nThe two-digit month in which a card expires. \n\nFormat: `MM` \n\nPossible values: 01 through 12\n"
expirationYear:
type: string
x-nullable: true
maxLength: 4
description: "One of two possible meanings:\n\nThe four-digit year in which a token expires.\nThe four-digit year in which a card expires. \n\nFormat: `YYYY` \n\nPossible values: 1900 through 3000 \n\nData type: Non-negative integer\n"
number:
type: string
x-nullable: true
maxLength: 20
description: 'Customer''s payment network token value.
'
securityCode:
type: string
x-nullable: true
maxLength: 4
description: 'Card Verification Number (CVN).
'
type:
type: string
x-nullable: true
maxLength: 3
description: 'Three-digit value that indicates the card type. Mandatory if not present in a token.
Possible values:
- `001`: Visa
- `002`: Mastercard, Eurocard, which is a European regional brand of Mastercard.
- `033`: Visa Electron
- `024`: Maestro
'
customer:
type: object
x-nullable: true
properties:
id:
type: string
maxLength: 32
x-nullable: true
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 become optional.\n\nIf you intend on using more than one token, please take note of the following conditions:\n\n- In case a Customer token is accompanied by an Instrument Identifier token, the card number from the Instrument Identifier token will take precedence over the Customer token.\n- The Customer token and the Payment Instrument token are mutually exclusive. If both are present, you will receive an error. \n\nFor more information on TMS, please see our originator-facing documentation.\n\nConditional: If the card and paymentInstrument object information is incomplete, this field becomes mandatory to re
# --- truncated at 32 KB (120 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cybersource/refs/heads/main/openapi/cybersource-pull-funds-api-openapi.yml