Creating an Internal Transfer

This guide describes the procedure for performing internal transfers using the Create Account Transfer and Reverse Account Transfer endpoints.

Follow this procedure to

  • Transfer funds from one account (sending account) to another account (receiving account) within the same Galileo client program. The accounts can belong to the same account holder or different account holders, and a fee can also be assessed.
  • Combine an adjustment, payment, and fee into one API call.
  • Reverse out any transfer that was created with Create Account Transfer.

📘

Note

If the accounts have different program IDs, program parameters must permit transfers between the programs.

Do not follow this procedure to

  • Transfer funds between a customer account and an ACH account; instead, follow the instructions in Creating an ACH transaction.
  • Transfer funds between an account provided by one Galileo client and an account provided by another Galileo client; instead, use the Create ACH Transaction endpoint or external bank-to-bank means such as wiring funds.

Result of calling Create Account Transfer

When the Create Account Transfer endpoint has been successfully called:

  • The specified amount is debited from the sending account (adjustment).
  • The specified amount is credited to the receiving account (payment).
  • If configured, a fee is assessed to the sending account.

The transaction types for transfers using the Create Account Transfer endpoint depend on the breakdown of the value in the type parameter. For example, if the type refers to a transfer that assesses a 20-cent fee on the sending account, a $50.00 transfer from PRN 33333 to PRN 77777 will produce these transactions:

pmt_ref_noact_typeamtexternal_trans_id
33333AD-50.00d930f-20e06
77777PM+50.00d930f-20e06
33333FE-0.20d930f-20e06

📘

Note

When initiating a transaction with the Program API, the transactionId from the API request is copied to the external transaction ID field of all transactions that result from the request. The external transaction ID is available in the responses to transaction-retrieval Program API requests as external_trans_id, in the Posted Transactions RDF as EXTERNAL TRANSACTION ID, and in the Events API webhook messages as ext_trans_id.

Result of calling Reverse Account Transfer

When the Reverse Account Transfer endpoint has been successfully called, he result of the original Create Account Transfer call is undone, meaning that:

  • The sending account is credited the original amount
  • The receiving account is debited the original amount
  • If applicable, the fee is reversed out from the sending account.

When reversing out the transfer, the transactions are recorded as adjustments and the fee is a fee with the sign reversed.

pmt_ref_noact_typeamtexternal_trans_id
33333AD+50.00d930f-20e06
77777AD-50.00d930f-20e06
33333FE+0.20d930f-20e06

Driving the sending account negative

By default, a transaction that drives the sending account below 0.00 is not allowed. To permit transactions created by Create Account Transfer to drive the sending account negative, set the ALWNB parameter on the sending account product. (In contrast, to permit the Create Adjustment endpoint to drive an account negative, ALWNB must be set at the provider level.)

Message fields

Banks require that all account transfers include a message with both the payment and the adjustment. You can determine which message to display by choosing from among these options:

  • Default message
  • Customization per transaction type
  • Cardholder-defined messages

Default message

By default, the string "Card to Card" is displayed for both the payment and the adjustment. You can change this default by requesting that Galileo populate the BMNAM product parameter. The message in BMNAM is then displayed for both the payment and the adjustment.

Customization per transaction type

You can request that Galileo set up a lookup table to supply a different message according to the sender product, activity (adj or pmt), and transaction types (specific to your program). For example, you could provide a table to Galileo with values such as these:

sender prod_idact_typeotypeMessage
9999ADmtTransfer to checking
9999PMmsTransfer from savings
9999ADCRTransfer to <firstname lastname>
9999PMCSTransfer from <firstname lastname>

In the messages you can include fields for the value in BMNAM as well as sender and recipient first and last names.

If a transaction does not match a prod_id/act_type/otype combination, the default message in BMNAM is displayed.

Cardholder-defined messages

You can provide the message and senderMessage fields for the cardholder to manually enter messages. To use these fields, Galileo must set the provider parameter C2DSC to 1.

The message and senderMessage parameters follow these rules:

  • When both parameters are populated:
    • The value in message is displayed on the payment.
    • The value in senderMessage is displayed on the adjustment.
  • When only message is populated:
    • The value in message is displayed on both the payment and the adjustment.
  • When only senderMessage is populated:
    • The value in senderMessage is displayed on the adjustment.
    • The payment message is the default message.
  • When neither field is populated, the default message is displayed.

Message hierarchy

Among the methods to define messages, this is the order of precedence:

  1. Cardholder-defined messages in message and senderMessage (provided that C2DSC is set)
  2. Lookup table, if it exists
  3. BMNAM value
  4. "Card to Card" (default value)

If a value is missing for a message, the message in the next level down is considered the default. For example, if you have a lookup table and you also provide the cardholder-defined messages, the cardholder-defined message will override the value in the lookup table, but if no value is provided by the cardholder, the value in the lookup table is used. If there is no value in the lookup table, the value in BMNAM is used.

Parameters

This table explains the parameters that are specific to the Create Account Transfer endpoint.

ParameterUsage
accountNoThe sending account number
amountThe amount to transfer, as a decimal or whole number.
transferToAccountNoThe receiving account number
messageCustomer-provided message to attach to the transaction. According to your provider parameters, the message will be in the payment description on the recipient's transaction.
typeYou determine valid values in cooperation with Galileo. If you do not pass a value for type these default transaction types are used:
Payment — C2
Adjustment — M
Fee — C2C

This table explains the parameters that are specific to the Reverse Account Transfer endpoint.

ParameterUsage
transactionIdThe transactionId of the API call to be reversed.
accountNoThe sending account number in the original API call.

Account-transfer workflow

This flowchart shows the logical progression of the Create Account Transfer endpoint. The actual sequence of events in the Galileo system may vary.

596596
  1. You send the Create Account Transfer request.
  2. Galileo performs a number of preliminary checks. Failures return the status codes shown in the diagram. Consult the Status codes table for next steps.
  3. Galileo verifies that the receiving account exists; if it does not, Galileo returns status: 445-01.
  4. Galileo checks program and product parameters to verify that the receiving account is eligible to receive this type of transfer; if it is not, Galileo returns status: 445-03.
  5. If the sending and receiving accounts are not in the same program, Galileo checks program parameters to verify that the receiving program is eligible to receive this type of transfer; if not, Galileo returns status: 445-07.
  6. Galileo verifies that the transaction does not violate velocity limits for either account; if it does, Galileo returns status: 445-04 for the sending account or status: 445-05 for the receiving account. If both accounts are in violation, only status: 445-04 is sent, because Galileo checks the sending account first.
  7. Galileo verifies that there are sufficient funds in the sending account; if not, Galileo returns status: 445-06.
  8. If all checks are successful, Galileo sends the response status: 0 and creates the transaction by debiting the sending account and crediting the receiving account.
  9. Galileo sends Transaction Events webhooks according to your specific configuration: BADJ: adj for the sending account and BPMT: pmt for the receiving account. If the payment type includes a fee, Galileo sends BFEE: fee for the sending account.

Account-transfer reversal workflow

The logical progression of the Reverse Account Transfer endpoint is as follows:

  1. The Galileo system locates the same transaction ID as for the Create Account Transfer call.
  2. The Galileo system creates new transactions with the sending and receiving accounts reversed: the amount is credited to the former sending account and debited from the former receiving account. If applicable the fee is also reversed out from the former sending account.
  3. The Galileo system sends Transaction Events webhooks, all BADJ: adj, showing a positive amount for the former sending account, a negative amount for the former receiving account, and a positive amount for the fee that was assessed to the former sending account.

Sample endpoint request and response

Consult the Create Account Transfer and Reverse Account Transfer references to see how to build the API request and to see the response schema.

Create Account Transfer status codes

Status codeDescriptionNext steps
0SuccessNone
2Your API call contained one or more values that were not valid for the parameter.Retry with valid values
12The value in accountNo is not a valid account number.Retry with valid account number.
24This API call was already submitted and successfully completed. The transaction IDs were identical.None. Duplicate API calls have no effect on the Galileo system.
445-01The value in transferToAccountNo does not exist in the Galileo system.Retry with a valid account number in transferToAccountNo or inform the customer that the receiving account does not exist.
445-02The transfer-to (receiving) account is in a non-active status.Verify that the receiving account is in the correct status, or inform the customer that the receiving account is ineligible to receive funds.
445-03The transfer-to (receiving) account product is not authorized to receive a transferInform the customer that the receiving account is not eligible to receive funds
445-04Moving funds out of this account violates its velocity limits.Inform the customer that they cannot make this transfer.
445-05Moving funds into this account violates its velocity limits.Inform the customer that they cannot make this transfer.
445-06The value in amount is higher than the sending account's available funds.Inform the customer that they do not have sufficient funds to make this transfer.
445-07The sending and receiving accounts are in different programs, and program settings do not permit transfers between these programs.Verify that your program settings permit transfers between the two programs, or inform the customer that they cannot transfer funds between those two accounts.
-1System failure. Possibly a network or database issue.Consult the response to see which steps to take.

Reverse Account Transfer status codes

Status codeDescriptionNext steps
0SuccessNone
2Your API call contained one or more values that were not valid for the parameter.Retry with valid values
12The value in accountNo is not a valid account number.Retry with valid account number.
31Unknown or unregistered transactionVerify that the transaction to be reversed exists.
496-01Insufficient balance for reversalFollow your business plan for this outcome.
-1System failure. Possibly a network or database issue.Consult the response to see which steps to take.

View the internal transfer

You can retrieve a record of the transfer or transfer reversal using one of these endpoints:


Did this page help you?