On This Page

Payouts Developer Guide

This section describes how to use this guide and where to find further information.

Audience and Purpose

This document is written for developers who want to use the
Cybersource
 APIs to integrate
Cybersource
Payouts
 services into their transaction management system.

Conventions

This special statement is used in this document:
An
Important
 statement contains information essential to successfully completing a task or learning a concept.

Related Documentation

Visit the
Cybersource
 documentation hub on the Cybersource Developer Center for links to further documentation resources.

Customer Support

For support information about any service, visit the Support Center:

Recent Revisions to This Document

25.01

Initial release.

Introduction to
Payouts

This introduction contains an overview of the
Payouts
 service and describes the supported recipient card types, currencies, transactions, and business application identifiers (BAIs) as well as requirements.

Overview

Payouts
 transfers funds from one account to another using a two-step model:
  • An
    account funding transaction
     (AFT) withdraws funds from a sender’s account using standard credit card processing.
  • An
    original credit transaction
     (OCT) deposits funds into a recipient’s account.
An AFT and OCT are independent transactions, though an AFT usually precedes a corresponding OCT.
In typical payment transactions, you initiate debits and credits to receive payments from cardholders for your goods and services. With
Payouts
, you provide a money transfer service by initiating AFT and OCT transactions that move funds between accounts:
  • A
    business-to-person
     payment moves funds between a merchant and a cardholder.
  • A
    person-to-person
     payment moves funds between two cardholders.
No merchant goods are involved in
Payouts
 transactions.
At present,
FDC Nashville Global
 supports AFT services only.
You must receive prior approval from
FDC Nashville Global
 before using the AFT services. Contact
FDC Nashville Global
 to register in the AFT program.

Supported Card Types

Recipient card type for AFTs:
  • Mastercard
  • Visa
Card types:
  • Mastercard
  • Visa
Currencies:
CAD, GBP, and
USD

Requirements

To use Payouts services, you must obtain approval from your acquirer for requesting this type of transaction.

AFT Transactions

The Account Funding Transaction (AFT) allows the transfer of funds between a payment card and another account, including other payment cards. When used independently, an AFT can only transfer funds between accounts owned by the same person or business entity. An AFT is not intended for paying goods and services, funding a merchant account, or repaying debts.
You must receive prior approval from
FDC Nashville Global
 before using the AFT services. Contact
FDC Nashville Global
 to register in the AFT program.

Dual Message Account Funding Transactions (AFTs)

Account Funding Transactions allow a payment service provider to debit funds from a cardholder's Mastercard or Visa account to fund a non-merchant account. This is typically used to load funds onto prepaid cards and electronic wallets.
Dual Message Account Funding Transactions (AFTs) provide the following benefits:
  • Enables customers to identify Mastercard and Visa transactions during the authorization and settlement.
  • Allows acquiring partners to use Dual Message BINs when performing a payout transaction.

Endpoint

Set the
ccAuthService_run
 field to
true
.
Send the request to
https://ics2ws.ic3.com/commerce/1.x/transactionProcessor
.

Required Fields for a Dual-Message AFT Request for
FDC Nashville Global

These fields are required to process a dual-message AFT request:
These are the values when using a Mastercard card type:
  • AA
    : Account-to-account.
  • BB
    : Business to business.
  • CO
    : Cash out.
  • CP
    : Card bill payment.
  • MD
    : Merchant disbursement (acquirers or aggregators settling to merchants).
  • PP
    : Person to person.
  • WT
    : When AFT is used to fund a staged digital wallet.
These are the values when a Visa card type:
  • AA
    : Account to account.
  • BI
    : Business to business.
  • CB
    : Consumer bill payment.
  • FT
    : Funds transfer.
  • PP
    : Person to person.
  • TU
    : Top Up: Prepaid load.
  • WT
    : Wallet transfer.
Required with Mastercard.
Required for Mastercard. These codes are permitted:
  • 00
    : Other
  • 01
    : Routing transit number (RTM) and bank account
  • 02
    : IBAN
  • 03
    : Card account
  • 04
    : Email
  • 05
    : Phone number
  • 06
    : Bank account number (BAN) and Bank identification number code (BIC)
  • 07
    : Wallet ID
  • 08
    : Social network ID
Required with Mastercard for domestic funding transactions when the transaction is a subsequent and cross-border funds transfer.
Required with Mastercard. Required with Visa for intra-European Economic Area (EEA), including UK and Gibraltar, and EU international transactions. Optional with Visa for domestic EU AFTs.
Required with Mastercard. Required with Visa for intra-European Economic Area (EEA), including UK and Gibraltar, and EU international transactions. Optional with Visa for domestic EU AFTs.
Required with Visa for intra-European Economic Area (EEA), including UK and Gibraltar, and EU international transactions. Optional with Visa for domestic EU AFTs and Mastercard.
Required with Visa in the EU.
Required with Visa transactions into and out of Canada with the address of the person or entity. Optional with Mastercard.
Required with Visa transactions into and out of Canada for cross-border money and non-money transfers. Optional with Mastercard.
Required with Visa transactions into and out of Canada. Optional with Mastercard.
Required with Visa. Optional with Mastercard.
Required with Visa EMV transactions.
Required with Visa. Optional with Mastercard.
Required with Visa. Optional with Mastercard.
This field contains the sender business, government, non-government name, or Visa payer name.
When this field is present in a transaction, the
senderInformation.firstName
,
senderInformation.middleName
, and
senderInformation.lastName
 fields should not be present in the transaction.
Strongly recommended with Visa.
These are the valid values:
  • ARNB
    : Alien registration number
  • BTHD
    : Date of birth
  • CPNY
    : Company registration number
  • CUID
    : Customer identification (unspecified)
  • DRLN
    : Driver license
  • EMAL
    : Email
  • LAWE
    : Law enforcement identification
  • MILI
    : Military identification
  • NTID
    : National identification
  • PASN
    : Passport number
  • PHON
    : Phone number
  • PRXY
    : Proxy identification
  • SSNB
    : Social security number
  • TRVL
    : Travel identification (non-passport)
  • TXIN
    : Tax identification
Required with Visa for transactions in Canada and US. Optional with Mastercard.

Optional Fields for a Dual-Message AFT

You can include these optional fields in an authorization request for an AFT:
These are the valid values:
  • 01
    : Credit (Visa or Mastercard credit card)
  • 02
    : Debit (Visa or Mastercard debit card)
  • 03
    : Prepaid (Visa or Mastercard prepaid card)
  • 04
    : Deposit account (checking, savings, or cryptocurrency)
  • 06
    : Cash
These are the valid values:
  • 00
    : Other
  • 01
    : Routing Transit Number (RTN) + Bank Account Number (BAN)
  • 02
    : International Bank Account Number (IBAN)
  • 03
    : Card Account
  • 04
    : Email
  • 05
    : Phone Number
  • 06
    : Bank Account Number (BAN) + Bank Identification Code (BIC), also known as a SWIFT code
  • 07
    : Wallet ID
  • 08
    : Social Media ID
This field is optional, but strongly recommended.
These are the valid values:
  • 0B
    : Business
  • 0I
    : Individual

Simple Order Example: Dual-Message AFT for
FDC Nashville Global

Request

        <requestMessage xmlns="urn:schemas-cybersource-com:transaction-data-1.221">
            <merchantID>en_vdcuruguay_1_ccs</merchantID>
            <merchantReferenceCode>TC55255-1</merchantReferenceCode>
            <invoiceHeader>
                <businessApplicationID>AA</businessApplicationID>
            </invoiceHeader>
            <billTo>
                <firstName>JHON</firstName>
                <lastName>SMITH</lastName>
                <street1>1-26-28 Nakashirane,</street1>
                <city>Yokohama-shi</city>
                <state>CA</state>
                <postalCode>602-8511</postalCode>
                <country>US</country>
                <phoneNumber>999-123-9999</phoneNumber>
                <email>test@visa.com</email>
            </billTo>
            <purchaseTotals>
                <currency>USD</currency>
                <grandTotalAmount>100</grandTotalAmount>
                <invoiceAmount>1234</invoiceAmount>
            </purchaseTotals>
            <card>
                <accountNumber>4111111111111111</accountNumber>
                <expirationMonth>12</expirationMonth>
                <expirationYear>2030</expirationYear>
                <cvNumber>123</cvNumber>
                <cardType>001</cardType>
            </card>
            <recipient>
                <postalCode>222120</postalCode>
                <accountID>987654321</accountID>
                <accountType>33</accountType>
                <lastName>last</lastName>
                <firstName>firstname</firstName>
                <middleName>middlename</middleName>
                <address>this is address1</address>
                <city>Newyork</city>
                <country>US</country>
            </recipient>
            <sender>
                <referenceNumber>REFNUM123</referenceNumber>
                <sourceOfFunds>02</sourceOfFunds>
                <name>justsenderName</name>
                <address>addressofthesender</address>
                <city>Newyork</city>
                <state>ca</state>
                <country>US</country>
                <accountNumber>154264765376576126571652675176</accountNumber>
                <firstName>Senderfirst</firstName>
                <middleName>SenderMiddle</middleName>
                <lastName>Senderlast</lastName>
                <personalIDType>TXIN</personalIDType>
                <type>B</type>
                <identificationNumber>23506907642323235</identificationNumber>
            </sender>
            <aft>
                <indicator>true</indicator>
            </aft>
        </requestMessage>
Response

        <c:replyMessage xmlns:c="urn:schemas-cybersource-com:transaction-data-1.221">
            <c:merchantReferenceCode>TC55255-1</c:merchantReferenceCode>
            <c:requestID>7193792686247001309916</c:requestID>
            <c:decision>ACCEPT</c:decision>
            <c:reasonCode>100</c:reasonCode>
            <c:requestToken>Axj/7wSThfntrctjncLcAHgs3YuWbdyybOGzJo3YMGLNg5csWybWNLQsAAU2saWhYBpA6cQQUYZNv/sXFU8Q64E5OF+e2ty2OdwtwAAA5xPu</c:requestToken>
            <c:purchaseTotals>
                <c:currency>USD</c:currency>
            </c:purchaseTotals>
            <c:ccAuthReply>
                <c:reasonCode>100</c:reasonCode>
                <c:amount>100.00</c:amount>
                <c:authorizationCode>831000</c:authorizationCode>
                <c:avsCode>Y</c:avsCode>
                <c:avsCodeRaw>Y</c:avsCodeRaw>
                <c:cvCode>M</c:cvCode>
                <c:cvCodeRaw>M</c:cvCodeRaw>
                <c:authorizedDateTime>2024-06-26T05:21:10Z</c:authorizedDateTime>
                <c:processorResponse>00</c:processorResponse>
                <c:reconciliationID>7193792686247001309916</c:reconciliationID>
                <c:merchantAdviceCode>01</c:merchantAdviceCode>
                <c:merchantAdviceCodeRaw>M001</c:merchantAdviceCodeRaw>
                <c:cavvResponseCode>2</c:cavvResponseCode>
                <c:cavvResponseCodeRaw>2</c:cavvResponseCodeRaw>
                <c:paymentNetworkTransactionID>016153570198200</c:paymentNetworkTransactionID>
                <c:reconciliationReferenceNumber>417805815972</c:reconciliationReferenceNumber>
            </c:ccAuthReply>
            <c:receiptNumber>815972</c:receiptNumber>
            <c:additionalData>ABC</c:additionalData>
            <c:card>
                <c:cardType>001</c:cardType>
            </c:card>
            <c:reserved>
                <ics_message xmlns="urn:schemas-cybersource-com:transaction-data:ics">
                    <ics_decision_reason_code>100</ics_decision_reason_code>
                    <auth_payment_network_transaction_id>016153570198200</auth_payment_network_transaction_id>
                    <auth_rcode>1</auth_rcode>
                    <receipt_number>815972</receipt_number>
                    <ics_return_code>1000000</ics_return_code>
                    <auth_merchant_advice_code>01</auth_merchant_advice_code>
                    <ics_rcode>1</ics_rcode>
                    <auth_cavv_response_code>2</auth_cavv_response_code>
                    <auth_auth_response>00</auth_auth_response>
                    <auth_rmsg>Request was processed successfully.</auth_rmsg>
                    <merchant_ref_number>TC55255-1</merchant_ref_number>
                    <auth_merchant_advice_code_raw>M001</auth_merchant_advice_code_raw>
                    <currency>USD</currency>
                    <auth_auth_code>831000</auth_auth_code>
                    <auth_auth_amount>100.00</auth_auth_amount>
                    <auth_cv_result_raw>M</auth_cv_result_raw>
                    <auth_fee_program_indicator>123</auth_fee_program_indicator>
                    <card_type>001</card_type>
                    <auth_additional_token_response_information>0</auth_additional_token_response_information>
                    <ics_rmsg>Request was processed successfully.</ics_rmsg>
                    <auth_trans_ref_no>7193792686247001309916</auth_trans_ref_no>
                    <request_id>7193792686247001309916</request_id>
                    <auth.reason_code>100</auth.reason_code>
                    <auth_cavv_response_code_raw>2</auth_cavv_response_code_raw>
                    <auth_auth_time>2024-06-26T052110Z</auth_auth_time>
                    <auth_rflag>SOK</auth_rflag>
                    <auth_cv_result>M</auth_cv_result>
                    <auth_return_code>1010000</auth_return_code>
                    <auth_avs_raw>Y</auth_avs_raw>
                    <ics_rflag>SOK</ics_rflag>
                    <auth_reconciliation_reference_number>417805815972</auth_reconciliation_reference_number>
                    <auth_auth_avs>Y</auth_auth_avs>
                    <request_token>Axj/7wSThfntrctjncLcAHgs3YuWbdyybOGzJo3YMGLNg5csWybWNLQsAAU2saWhYBpA6cQQUYZNv/sXFU8Q64E5OF+e2ty2OdwtwAAA5xPu</request_token>
                    <additional_data>ABC</additional_data>
                </ics_message>
            </c:reserved>
            <c:additionalToken>
                <c:responseInformation>0</c:responseInformation>
            </c:additionalToken>
        </c:replyMessage>

Business Application Identifier Values

The Business Application Identifier (BAI) is used to identify the category of the Account Funding Transaction (AFT). Provide one of the values when you send field
invoiceHeader_businessApplicationID
.
All acquirers, service providers, and merchants are required to submit a valid BAI value when submitting AFTs.
Ensure your acquirer has a Merchant Category Code (MCC) that aligns with the BAI values you are using. For more information, contact your acquirer.
Business Application Identifier Values
BAI Value
Category
Requirements
AA
Account-to-Account Money Transfer. The funding of the cardholder's own account at the same or a different financial institution Both accounts must be owned by the same person/entity.
If funding a prepaid account, don't use this value, use
TU
.
BB
Business to Business
BI
Financial Institution offered Bank-Initiated P2P Money Transfer
P2P Money Transfer is initiated from an online banking system, making it a bank-initiated transaction. This category is only used for specific scenarios and only available in limited markets. For more information, contact your Visa representative.
This value is only available with Visa card types.
CB
Consumer Bill Payment
This value is only available with Visa card types.
CO
Cash Out
CP
Cash Bill Payment
FD
Funds Disbursement
Available only with Visa card transactions.
FT
Funds Transfer
If the funds will be used for a high-brand risk transaction, the applicable high-brand risk MCC must be used. If a wallet is used to purchase Liquid and Cryptocurrency assets, the applicable special condition indicator must be used.
This value is only available with Visa card types.
GD
Government disbursement, including:
  • Government-initiated tax refunds
  • Government benefit and welfare disbursements
This value is only available with Visa card types.
GP
Gambling payout other than online gambling.
This value is only available with Visa card types.
LO
Loyalty credits and rebates (not supported in European systems).
This value is only available with Visa card types.
NA
Merchant instant funding.
This value is only available with Visa card types.
MI
Merchant-initiated money transfer.
This value is only available with Visa card types.
MD
Merchant disbursement (acquirers or aggregators settling to merchants).
PD
Payroll Disbursement
This value is only available with Visa card types.
PP
Person-to-Person (P2P) Money Transfer
P2P Money Transfer is initiated from an online banking system, making it a bank-initiated transaction. This category is only used when both AFTs and OCTs are supported. When only AFT is supported, use the
FT
 category.
TU
Prepaid Card Load or Top-Up
This value is only available with Visa card types.
WT
Staged Digital Wallet (SDW) Transfer
If the funds will be used for a high-brand risk transaction, the applicable high-brand risk MCC must be used. If the funds are used for a gambling transaction, the applicable gambling MCC must be used. If a wallet is used to purchase Liquid and Cryptocurrency assets, the applicable special condition indicator must be used. An AFT is not intended for debt repayment.

Recipient Account

The Sender Source identifies the source of funds. Provide one of the values when you send field
recipient_accountType
.
Recipient Account Values
Value
Definition
00
Other
01
RNT 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

Sender Source

The Sender Source identifies the source of funds. Provide one of the values when you send field
sender_sourceOfFunds
.
All acquirers, service providers, and merchants are required to submit a valid sender source value when submitting AFTs.
Sender Source Values
Value
Definition
01
Credit Card
02
Debit Card
03
Prepaid Card
04
Deposit Account
06
Cash