Creating an Internal Transfer

This guide describes the procedure for performing internal transfers using the Create Account Transfer endpoint.

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 a transfer that was created with Create Account Transfer.

📘

Note

If the sending and receiving 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:

📘

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.

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
• Customer-defined messages

📘

Note

The messages do not accept international characters—only letters, numbers, spaces, and punctuation.

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:

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.

Customer-defined messages

You can provide the message and senderMessage fields for the customer to manually enter messages. To use these fields, C2DSC must be set.

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. Customer-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 customer-defined messages, the customer-defined message will override the value in the lookup table, but if no value is provided by the customer, 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.

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.

1. You send the Create Account Transfer request.
2. Galileo verifies that the receiving account exists; if it does not, the endpoint returns status_code: 445-01.
3. Galileo verifies that the receiving account is in status N, L or S. If it is not, the endpoint returns status_code: 445-02.
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, the endpoint returns status_code: 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, the endpoint returns status_code: 445-07.
6. Galileo verifies that the transaction does not violate velocity limits for either account; if it does, the endpoint returns status_code: 445-04 for the sending account or status_code: 445-05 for the receiving account. If both accounts are in violation, only status_code: 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, the endpoint returns status_code: 445-06.
8. If all checks are successful, the endpoint returns status_code: 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

Although the Program API has a Reverse Account Transfer endpoint, Galileo recommends that you not use it to reverse account transfers, because of the way that endpoint handles transaction codes. If you use the Reverse Account Transfer endpoint, the reversed transactions will not have transaction codes that indicate that they are reversals of previous transactions.

Instead, when you design your funds-flow schema with Galileo, make sure that you have otypes that designate the appropriate transfer reversals. Using the Create Adjustment endpoint, reverse out both the payment and adjustment in separate calls, using the corresponding reversal otypes for type. For the fee, use Reverse Fee.

View the internal transfer

You can retrieve a record of the transfer using any endpoint that returns posted transactions:

• Get Account Overview
• Get Transaction History
• Get All Transaction History

📘

Note

There is a delay of several seconds before a transfer appears in a customer’s transaction history.

You can also see the transactions in the Posted Transactions RDF.

Sample endpoint request and response

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

Status codes

Consult the Create Account Transfer reference for status codes and next steps.