This guide describes the procedure to move funds into a customer account, make payment reversals, and update payment hold days using the <a href="ref:post_createpayment" target="_blank">Create Payment</a> and <a href="ref:post_updatepayment" target="_blank">Update Payment</a> endpoints.


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.

  • 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:

  • Remove funds from an account; instead, consult <a href="doc:about-adjustments" target="_blank">Creating an Adjustment</a>.

  • Transfer funds from one account to another in the same program; instead, use the <a href="doc:creating-an-internal-transfer" target="_blank">Creating an Internal Transfer</a> procedure.

Also see <a href="doc:about-adjustments#payments-vs-adjustments" target="_blank">Payments vs. adjustments</a> in the _Creating an Adjustment_ guide.

## 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 <a href="ref:post_createpayment" target="_blank">Create Payment</a> 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 the system is configured to assess a 15-cent fee for retail loads (otype RL), calling Create Payment would produce these transactions:


## Result of calling Update Payment

The hold days for the original <a href="ref:post_createpayment" target="_blank">Create Payment</a> 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.

## Creating a payment

Prior to creating a payment, you can call the <a href="ref:post_verifyaccount" target="_blank">Verify Account</a> endpoint and pass the intended payment otype in the `loadType` parameter. The endpoint returns these values:

  • `max_load_amount` — The maximum amount configured for the payment type.

  • `balance` — The available balance (open to buy) on the account.

  • `account_status` — The current <a href="ref:api-reference-account-statuses" target="_blank">account status</a>. Only some statuses permit payments.

Using these values you can determine whether to call Create Payment or whether to notify the account holder that the payment cannot be made at this time.

### Create Payment parameters

This table explains parameters for the <a href="ref:post_createpayment" target="_blank">Create Payment</a> endpoint.

`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:<br> `0` — Galileo<br>`1` — Provider<br>`2` — 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 <a href="ref:post_assessfee" target="_blank">Assess Fee</a> endpoint.
Merchant and store parametersUsed 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 <a href="ref:post_getholdhistory" target="_blank">Get Hold History</a> endpoint. To manually expire a hold created in this way, use the <a href="ref:post_expirehold" target="_blank">Expire Hold</a> endpoint.

### Create Payment workflow

This flowchart shows the logical progression of the <a href="ref:post_createpayment" target="_blank">Create Payment</a> endpoint. The actual sequence of events in the Galileo system may vary.


  1. You send the <a href="ref:post_createpayment" target="_blank">Create Payment</a> request.

  2. Galileo performs a number of preliminary checks. Failures return the status codes shown in the diagram.

  3. Galileo verifies that the payment is within load limits for the receiving account. If it is not, the endpoint returns `status_code: 408-01`.

  4. The endpoint sends `status_code: 0`.

  5. If the `holdDays` parameter was populated, Galileo waits until the hold days expire.

  6. Galileo creates the transaction by crediting the receiving account. If a load limit was violated, Galileo creates a payment for a partial amount.

  7. Galileo sends <a href="ref:transaction-events-webhook" target="_blank">Transaction Events</a> webhook <a href="ref:api-reference-events-api-pmt" target="_blank">`BPMT: pmt`</a> for the receiving account.


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 <<glossary:RDF>> as `EXTERNAL TRANSACTION ID`, and in the Events API webhook messages as `ext_trans_id`.

## Updating a payment

You can update the hold days on a payment that has not been processed. The payment must be in `status: R` (ready to process) to be updated.

### Update Payment parameters

This table explains parameters for the <a href="ref:post_updatepayment" target="_blank">Update Payment</a> endpoint.

`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 `payment_trans_id` by the Create Payment endpoint or 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.

### Update Payment workflow

The logical progression of the <a href="ref:post_updatepayment" target="_blank">Update Payment</a> endpoint is as follows:

  1. Galileo looks for the payment ID. If it cannot find it, Galileo returns `status: 533-01`.

  2. Galileo verifies that the payment is in `status: R`. If it is not, Galileo returns `status: 533-02`.

  3. Galileo updates the number of days to hold the payment. If the updated value is 0, Galileo posts the payment immediately.

## Reversing a Payment

Although the Program API has a Reverse Payment endpoint, Galileo recommends that you not use it to reverse a payment, because of the way that endpoint handles transaction codes. If you use the Reverse Payment endpoint, the reversed transaction will not have a transaction code that indicates that it is the reversal of a previous transaction.

Instead, when you design your funds-flow schema with Galileo, make sure that you have an otype that designates a reversal for each type of payment. Using the <a href="ref:post_createadjustment" target="_blank">Create Adjustment</a> endpoint, reverse the original payment by using the corresponding reversal otype for `type`.

## Viewing payments

You can view a record of payments deposited to a customer account using any endpoint that returns posted transactions:

  • <a href="ref:post_getaccountoverview" target="_blank">Get Account Overview</a>

  • <a href="ref:post_gettranshistory" target="_blank">Get Transaction History</a>

  • <a href="ref:post_getalltranshistory" target="_blank">Get All Transaction History</a>


There is a delay of several seconds before a payment appears in a customer’s transaction history and account overview.

## Sample endpoint request and response

Consult the <a href="ref:post_createpayment" target="_blank">Create Payment</a> and <a href="ref:post_updatepayment" target="_blank">Update Payment</a> endpoints to see how to build the API request and to see the response schema.

## Status codes

Consult the <a href="ref:post_createpayment" target="_blank">Create Payment</a> and <a href="ref:post_updatepayment" target="_blank">Update Payment</a> endpoints for status codes and next steps.