Account funding
Use Account Funding Transactions (AFT) to let customers load a wallet, prepaid card or investment account with their card.
An Account Funding Transaction (AFT) charges your customer's Visa or Mastercard card to load funds into another account. Your customer starts the payment in your service, and the transaction is sent to the card scheme as a dedicated AFT message instead of a regular purchase.
Typical uses:
- Topping up a digital wallet or prepaid card.
- Card-to-card transfers.
- Funding a brokerage or investment account.
Card schemes require AFTs for specific Merchant Category Codes (MCC), and the required data can differ per MCC.
Activation required
Your account must be enabled and registered for AFTs. Without that, AFT requests can be rejected. Whether AFTs apply to your business depends on your Merchant Category Code.
Create an AFT
Create an order with a credit-card transaction, add the receiver of the funds in payment_method_details, and send a complete billing address:
curl https://api.dev.gingerpayments.com/v1/orders/ \
--user "$API_KEY:" \
--header "Content-Type: application/json" \
--data '{
"currency": "EUR",
"amount": 5000,
"merchant_order_id": "TOPUP-001",
"description": "Wallet top-up",
"return_url": "https://www.example.com/order/TOPUP-001",
"transactions": [
{
"payment_method": "credit-card",
"payment_method_details": {
"receiver_account_number": "123456",
"receiver_account_number_type": "card-account"
}
}
],
"customer": {
"first_name": "John",
"last_name": "Doe",
"address_type": "billing",
"address": "Damrak 1",
"postal_code": "1012 LG",
"city": "Amsterdam",
"country": "NL"
}
}'The transaction in the response has transaction_type set to aft. From here, the payment continues like any other card payment, with the hosted payment page or a server-to-server integration.
Receiver details
Identify the account that receives the funds in the transaction's payment_method_details:
| Field | Description |
|---|---|
receiver_account_number | Account number of the receiver, 1 to 50 characters. |
receiver_account_number_type | Type of the account number, such as card-account. See create an order in the API reference for all values. |
Billing address
AFTs require a complete billing address in the customer object. Send at least:
| Field | Description |
|---|---|
first_name | Customer's first name. |
last_name | Customer's last name. |
address_type | Must be billing. |
address | Street and house number. |
postal_code | Postal code. |
city | City. |
state | Two-letter state, province or territory code. Required only when country is US or CA. |
country | ISO 3166-1 alpha-2 country code, such as NL. |
State codes
Use one of these values for state:
| Country | Allowed values |
|---|---|
Canada (CA) | AB BC MB NB NL NS NT NU ON PE QC SK YT |
United States (US) | AA AE AK AL AP AR AZ CA CO CT DC DE FL GA HI IA ID IL IN KS KY LA MA MD ME MI MN MO MS MT NC ND NE NH NJ NM NV NY OH OK OR PA RI SC SD TN TX UT VA VT WA WI WV WY |
Authorize first, capture later
AFTs support pre-authorizations. Set capture_mode to manual or delayed on the transaction:
{
"transactions": [
{
"payment_method": "credit-card",
"capture_mode": "manual",
"payment_method_details": {
"receiver_account_number": "123456",
"receiver_account_number_type": "card-account"
}
}
]
}The rest of the request is the same as above. Once the AFT is authorized, use the standard endpoints to capture or void it, in full or in part.