Creating a Payment
This guide describes the procedure to move funds into a customer account, make payment reversals, and update payment hold days using the Create Payment, Reverse Payment, and Update Payment endpoints.
Note
Galileo uses the term "payment" to refer to funds that are deposited into a customer account by the Create Payment endpoint and by other internal processes.
Follow this procedure to:
- Move funds into a customer account at a time other than account creation, such as when a customer deposits a paper check, cash, or receives a loan.
- Test whether funds can be deposited into a customer account.
- Reverse a payment and check for any reversal fees.
- Update the hold days for a pending payment.
Do not follow this procedure to:
- Transfer funds from one account to another in the same program; instead, use the Creating an Internal Transfer procedure.
Result of calling Create Payment
- The specified amount is credited to the receiving account.
- If configured, a fee is assessed to the sending (or sometimes receiving) account.
The transaction types for deposits using the Create Payment endpoint depend on the value in the type
parameter. For example, if a $100.00 retail load is made to the receiving account PRN 77777, and a 15-cent fee is assessed for retail loads, calling Create Payment may produce these transactions:
pmt_ref_no | pmt_type | amt | external_trans_id |
---|---|---|---|
77777 | RL | 100.00 | 39e5-14a2 |
77777 | FE | -0.15 | 39e5-14a2 |
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 asexternal_trans_id
, in the Posted Transactions RDF asEXTERNAL TRANSACTION ID
, and in the Events API webhook messages asext_trans_id
.
Result of calling Reverse Payment
The result of the original Create Payment call is undone, meaning that:
- The receiving account is debited the original amount.
- If applicable, the fee is reversed back to the account on which it was assessed.
- If configured, a reverse payment fee is assessed on the receiving account.
Note
For most payment reversals, Galileo recommends using the Create Adjustment endpoint instead of Reverse Payment. See Reversing payments and adjustments in the About Adjustments guide for an explanation.
When reversing a payment, the transactions are recorded as adjustments and the fee is a fee with the sign reversed.
pmt_ref_no | pmt_type | amt | external_trans_id |
---|---|---|---|
77777 | AD | -100.00 | 39e5-14a2 |
77777 | AD | 0.15 | 39e5-14a2 |
77777 | FE | -0.25 | 39e5-14a2 |
Result of calling Update Payment
The hold days for the original Create Payment call are updated, meaning that:
- Previously configured hold days for the product are replaced with the specified number.
- If the number of hold days is changed to zero, the hold is removed.
Parameters
This table explains parameters for the Create Payment endpoint.
Parameter | Usage |
---|---|
accountNo | The receiving account number. |
amount | The amount to transfer, as a decimal or whole number. |
type | You determine valid values in cooperation with Galileo. |
description | Your description of the transaction, if you provide one. |
location | Unique identifier for the location where the payment occurs. |
locationType | If the location type is 0 or 1 , the payment will be allowed or disallowed based on the location. Location types are:0 — Galileo1 — Provider2 — Don't validate load |
verifyOnly | Pass 1 to verify parameter values in your API call without creating a payment. |
providerAssessedFee | If a fee is assessed, pass the amount of the fee for informational purposes. To assess the actual fee, use the Assess Fee endpoint. |
Merchant and store parameters | Used by some retail locations that load funds onto cards. |
holdAmount | Amount of the payment to hold. |
holdExpirationDateTime | When to expire the hold. |
holdDescription | A description for the hold. |
holdExternalId | An alternate ID for the hold. |
When you populate the hold-related parameters, Galileo returns a hold_id
that you can retrieve using the Get Hold History endpoint. To manually expire a hold created in this way, use the Expire Hold endpoint.
This table explains parameters for the Reverse Payment endpoint.
Parameter | Usage |
---|---|
transactionId | The transactionId for the transaction (API call) to be reversed. |
accountNo | The receiving account number in the original API call. |
This table explains parameters for the Update Payment endpoint.
Parameter | Usage |
---|---|
accountNo | The receiving account number in the original API call. |
pmtId | The payment ID for the payment to be updated. This value is returned as pmt_id by the Get Payment History endpoint. |
holdDays | Number of days to hold the payment. Pass 0 to post the payment to the receiving account the next time payments are posted. |
Create payment workflow
This flowchart shows the logical progression of the Create Payment endpoint. The actual sequence of events in the Galileo system may vary.

- You send the Create Payment request.
- Galileo performs a number of preliminary checks. Failures return the status codes shown in the diagram. Consult the Status codes table for next steps.
- Galileo verifies that the payment is within load limits for the receiving account. If it is not, Galileo returns
status: 408-01
. - Galileo sends the response
status: 0
and creates the transaction by crediting the receiving account. - Galileo sends Transaction Events webhook
BPMT: pmt
for the receiving account.
Payment reversal workflow
The logical progression of the Reverse Payment endpoint is as follows:
- The Galileo system looks for the transaction ID that matches the original Create Payment request.
- The Galileo system verifies that there are sufficient funds for payment reversal in the account. If there are not, Galileo returns
status: 411-01
. - The Galileo system reverses the payment so that it is debited from the account.
Payment update workflow
The logical progression of the Update Payment endpoint is as follows:
- The Galileo system looks for the transaction ID that matches the original Create Payment endpoint.
- Galileo looks for the payment ID that matches the original Create Payment request. If it does not, Galileo returns
status: 533-01
. - Galileo verifies that the payment is set to
status: R
. If it is not, Galileo returnsstatus: 533-02
. - The Galileo system updates the number of days to hold the payment.
Sample endpoint request and response
Consult the Create Payment, Reverse Payment, and Update Payment endpoints to see how to build the API request and to see the response schema.
Status codes
Create payment status codes
Status code | Description | Next steps |
---|---|---|
0 | Success | None |
2 | Your API call contained one or more values that were not valid for the parameter. | Retry with valid values. |
12 | The value in accountNo is not a valid account number. | Retry with valid account number. |
24 | This API call was already submitted and successfully completed. The transaction IDs were identical. | None. Duplicate API calls have no effect on the Galileo system. |
25 | The value in type is not a valid type. | Retry with valid type. |
26 | The load amount or transaction count exceeds product limits. | Inform the customer that the load amount or transaction count exceeds the limit. |
100 | The value in verifyOnly was 1 and all parameter values passed verification. | None |
408-01 | The value in amount exceeds the maximum account load and will only be partially applied. | Inform the customer the payment only partially loaded to the account. |
-1 | Indicates that the application record failed to update or return. | Consult the response to see which steps to take. |
Reverse payment status codes
Status code | Description | Next steps |
---|---|---|
0 | Success | None |
2 | Your API call contained one or more values that were not valid for the parameter. | Retry with valid values. |
12 | The value in accountNo is not a valid account number. | Retry with valid account number. |
24 | This API call was already submitted and successfully completed. The transaction IDs were identical. | None. Duplicate API calls have no effect on the Galileo system. |
25 | The value in type is not a valid type. | Retry with valid type. |
27 | The value in transactionId does not exist in the Galileo system. | Retry with valid transaction ID or inform the customer that the transaction does not exist. |
32 | The value in transactionId does not match the transaction ID for the original Create Payment call. | Retry with the correct transaction ID. |
100 | The value in verifyOnly was 1 and all parameter values passed verification. | None |
411-01 | Payment cannot be reversed due to insufficient funds in the account. | Follow your business plan for this event. |
411-02 | Payment failed to reverse all pending holds. | Follow your business plan for this event. |
-1 | Indicates that the application record failed to update or return. | Consult the response to see which steps to take. |
Update payment status codes
Status code | Description | Next steps |
---|---|---|
0 | Success | None |
2 | Your API call contained one or more values that were not valid for the parameter. | Retry with valid values. |
12 | The value in accountNo is not a valid account number. | Retry with valid account number. |
533-01 | The value in pmtId does not match any payment record. | Retry with a valid payment ID. |
533-02 | The payment is not in status: R (ready to process). | Verify that the payment is in status: R . |
-1 | Indicates that the application record failed to update or return. | Consult the response to see which steps to take. |
Get payment history
You can view a record of payments deposited to a customer account using the Get Payment History endpoint. You can also use the endpoints that retrieve a comprehensive list of transactions, such as Get Account Overview or Get Transaction History.
Updated 8 months ago