Reloading an account
Reloads refer to users charging their credit card in order to add funds to their account (or someone else's via an EGift).
Reloads take advantage of Spoonity's vast array of payment gateway integrations to abstract payment handling away from developers.
The reload workflow
The typical reload workflow follows a consistent pattern:
- customer adds a billing profile to their account
- customer performs a charge
- (optional) charge is monitored to determine if it was successful
- account is loaded with the new funds
Requirements around monitoring or validating charges vary between gateway integrations.
Manage billing profiles
Billing profiles represent a customer's credit card, tokenized via an approved payment gateway, and managed by the Spoonity platform.
Users can add as many billing profiles as they'd like, and select which one they're prefer to use when performing reloads.
Because billing profiles are tokenized, they can not be updated after creation. They can be deleted, however. Credit cards that expire are not automatically removed from the user's account, but the Spoonity platform will send reminder emails to users about pending expiries in order to prevent disruption.
More details about our billing profile APIs can be found in the Billing Profile section.
Add a new billing profile
Customers add credit cards to their account through the billing profile process. It requires the user entering their credit card details, which are then tokenized before being stored within the Spoonity platform.
Raw credit card details are never stored within the Spoonity platform.
Add a new billing profile
curl -G https://api.spoonity.com/user/billing-profile/add?session_key={session_key} \
-d '{
"name": "Test Card",
"number": "4242424242424242",
"expiry_month": "03",
"expiry_year": "2026",
"cvv": "123",
"description": "Visa TEST PP",
"zip_code":"k1n1k2"
}'
Delete a billing profile
Deleting a billing profile fully removes it from the user's account, and prevents any additional charges from being applied against it.
Delete a billing profile
curl -G https://api.spoonity.com/user/billing-profile \
--request DELETE \
-d '{
"user_billingProfile_id: {user_billingProfile_id}
}'
Mark a billing profile as the default
The auto-reload and in-store checkin processes perform authorized background charges against a user's saved billing profiles. In order for the platform to know which billing profile to use in these automated scenarios, the user must set one as the default.
Mark a billing profile as the default
curl -G https://api.spoonity.com/user/billing-profile/default?session_key={session_key} \
-d '{
"user_billingProfile_id: {user_billingProfile_id}
}'
Process a charge
Reloads are processed by "charging" a user's billing profile. This process will issue a payment request against the user's credit card, and once the gateway notifies the platform of a successful payment, we load the same amount onto the user's account balance.
Charge a billing profile
Charge requests take a user_billingProfile_id and an amount. This informs the platform how much to charge the user's credit card, as well as which card to use.
Charge a billing profile
curl -G https://api.spoonity.com/user/billing-profile/reload?session_key={session_key} \
-d '{
"user_billingprofile": 69206,
"amount": 15
}'
Check the status of a pending charge
In some cases, the underlying payment gateway integration will not inform the Spoonity platform of the status of the charge immediately. In these cases, we can make use of the GET /user/billing-profile/reload/status API to check with the gateway after-the-fact.
Check the status of a pending charge
curl -G https://api.spoonity.com/user/billing-profile/reload/status?session_key={session_key}&transaction={transaction_id}
Manage auto reload settings
Users can optionally enable "auto reload" for their account. These settings allow them to set a minimum account balance threshold, and an amount to automatically reload to their account whenever they hit that threshold.
Get auto reload settings
This request returns the current auto reload settings to the user.
Get auto reload settings
curl -G https://api.spoonity.com/user/reload/settings?session_key={session_key}
Update auto reload settings
This request allows the user to set their threshold and amount. It also allows them to specify which billing profile should be used to charge against. All three values must be supplied in order to enable auto reload.
Setting either the threshold or amount to 0, or the user_billingProfile_id to null would disable auto reload for the user.
Update auto reload settings
curl -G https://api.spoonity.com/user/reload/settings?session_key={session_key} \
--request PUT \
-d '{
"amount": 10.00,
"threshold": 5.00,
"user_billingprofile": 69235
}'
Send an EGift
Reloads allow users to add balance to their own accounts. EGifts provide a medium for users to "send" funds to other users.
The process is similar to a normal reload, with one major difference. For EGifts, after the charge is processed, an email is dispatched to the intended "recipient" , which includes information about how they can redeem the funds.
In most cases, recipients must already have an account with the merchant where the EGift was dispatched to, or they must create one in order to accept the funds.
Send an EGift
We support both authenticated and unauthenticated (guest) EGifts.
Authenticated EGifts are the most basic, and function nearly identically to a normal reload. Here, users provide an amount and a user_billingProfile_id to charge against.
For guest EGifts, the user must instead provide the credit card details directly, exactly as they would as part of the "add a billing profile" workflow.
Send an EGift
curl -G https://api.spoonity.com/vendor/{vendor_id}/egift \
-d '{
"amount": 20.00,
"buyer": {
"name": "Grace Duncan",
"email": "grace@spoonity.com"
},
"recipient": {
"name": "Grace Duncan",
"email": "grace+1@spoonity.com"
},
"message": "yew get a gift",
"billing": {
"name":"Test Card",
"number":"4242424242424242",
"expiry":{
"month":"06",
"year":"19"
},
"cvv":"123",
"zip_code":"k1n1k2"
},
"image_url": null
}'