Billing Profile
Billing profiles represent tokenized payment credit cards added to end-customer accounts. Billing profiles are referenced whenever a charge is to be applied against an end-customer.
Retrieve a list of billing profiles
This request returns information about the user's billing profiles. User billing profiles link to a user's credit card through a token facilitated by a payment gateway. Information specific to the card is never stored in our systems, only details about this link.
Query parameters
- Name
session_key- Type
- string
- Description
Session token for an end-customer.
Response attributes
- Name
card- Type
- string
- Description
Returns the first and last 4 digits of the credit card number linked to this profile.
- Name
created- Type
- integer
- Description
The date this billing profile was created, listed as a Unix timestamp in seconds from 1970-01-01 00:00:00.
- Name
expiry- Type
- integer
- Description
The expiry date found on this card, listed as a Unix timestamp in seconds from 1970-01-01 00:00:00.
- Name
id- Type
- integer
- Description
An internal reference number that identifies this billing profile.
- Name
is_default- Type
- boolean
- Description
Indicates if this billing profile has been set as the default.
- Name
name- Type
- string
- Description
User specific card reference, as it was entered in the description when the card was added.
- Name
postal_code- Type
- string
- Description
The postal or zip code that is associated with the card's billing address.
- Name
type- Type
- string
- Description
Indicates the type of card in a way that is user friendly.
Request
curl -G https://api.spoonity.com/user/billing-profile/list?session_key={session_key}
Response
{
"count": 1,
"data": [
{
"card": "4242 xxxx xxxx 4242",
"created": 1559737156,
"expiry": 1561852800,
"id": "69206",
"is_default": true,
"name": "Visa TEST PP",
"object": "user_billingprofile",
"postal_code": "k1n1k2",
"type": "Visa"
}
],
"next_page_url": null,
"object": "collection",
"page": 1,
"page_size": 10,
"previous_page_url": null,
"total_pages": 1
}
Create a billing profile
This request is responsible for creating a new billing profile on a user's account and adding a credit card to this profile. The user must have an active login session and supply a card number, card name, expiry date and security code for the card.
Query parameters
- Name
session_key- Type
- string
- Description
Session token for an end-customer.
Required attributes
- Name
name- Type
- string
- Description
The name of the cardholder.
- Name
number- Type
- string
- Description
The card number.
- Name
expiry_month- Type
- string
- Description
The month this card expires (mm).
- Name
expiry_year- Type
- string
- Description
The year this card expires (yyyy).
- Name
cvv- Type
- string
- Description
The security code found on the back of this card.
- Name
description- Type
- string
- Description
A description attached to this card for the user's reference, helps distinguish this card from others.
- Name
zip_code- Type
- string
- Description
The postal or zip code associated with the billing address for this card.
Response attributes
- Name
card- Type
- string
- Description
Returns the first and last 4 digits of the credit card number linked to this profile.
- Name
created- Type
- integer
- Description
The date this billing profile was created, listed as a Unix timestamp in seconds from 1970-01-01 00:00:00.
- Name
expiry- Type
- integer
- Description
The expiry date found on this card, listed as a Unix timestamp in seconds from 1970-01-01 00:00:00.
- Name
id- Type
- integer
- Description
An internal reference number that identifies this billing profile.
- Name
name- Type
- string
- Description
User specific card reference, as it was entered in the description when the card was added.
- Name
type- Type
- string
- Description
Indicates the type of card in a way that is user friendly.
Request
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"
}'
Response
{
"card": "4242 xxxx xxxx 4242",
"created": 1559737156,
"expiry": 1561852800,
"id": "69206",
"name": "Test Card",
"object": "user_billingprofile",
"type": "Visa"
}
Set a default billing profile
This request marks a specific billing profile as the default billing profile to be used. This means that the card linked to this profile will be automatically charged as the payment method on an order, unless specified otherwise.
Query parameters
- Name
session_key- Type
- string
- Description
Session token for an end-customer.
Required attributes
- Name
user_billingProfile_id- Type
- integer
- Description
The identifier of the billing profile to be set as the default.
Request
curl -G https://api.spoonity.com/user/billing-profile/default?session_key={session_key} \
-d '{
"user_billingProfile_id: {user_billingProfile_id}
}'
Response
{}
Delete a billing profile
This request deletes a billing profile from a user's account. A billing profile cannot be edited, so this request may also be used as a step of "editing" such a profile. The profile is deleted, then the user_billingProfile_add can be used to re-add this card with the new information.
Query parameters
- Name
session_key- Type
- string
- Description
Session token for an end-customer.
Required attributes
- Name
user_billingProfile_id- Type
- integer
- Description
The identifier of the billing profile to be deleted.
Request
curl -G https://api.spoonity.com/user/billing-profile \
--request DELETE \
-d '{
"user_billingProfile_id: {user_billingProfile_id}
}'
Response
{}
Retrieve auto reload settings
This request returns the current settings for the user's automatic reload configuration. This information can also be found using the user_profile_read request in the "Profile" workflow, however that request returns more information than may be desired, and takes slightly longer to do so. If the billing profile is "null", automatic reload is turned of, regardless of the values for the reload amount and threshold.
Query parameters
- Name
session_key- Type
- string
- Description
Session token for an end-customer.
Response attributes
- Name
card- Type
- string
- Description
Returns the first and last 4 digits of the credit card number linked to this profile.
- Name
created- Type
- integer
- Description
The date this billing profile was created, listed as a Unix timestamp in seconds from 1970-01-01 00:00:00.
- Name
expiry- Type
- integer
- Description
The expiry date found on this card, listed as a Unix timestamp in seconds from 1970-01-01 00:00:00.
- Name
id- Type
- integer
- Description
An internal reference number that identifies this billing profile.
- Name
name- Type
- string
- Description
User specific card reference, as it was entered in the description when the card was added.
- Name
type- Type
- string
- Description
Indicates the type of card in a way that is user friendly.
- Name
reload_amount- Type
- float
- Description
How much the user would like to add to their account during an automatic reload, must be greater than 0.
- Name
reload_threshold- Type
- float
- Description
The point at which the user would like their account to automatically reload.
Request
curl -G https://api.spoonity.com/user/reload/settings?session_key={session_key}
Response
{
"anonymous": false,
"billing_profile": {
"card": "4242 xxxx xxxx 4242",
"created": 1559850677,
"expiry": 1561852800,
"id": "69212",
"name": "Visa Test PP",
"object": "user_billingprofile",
"status": {},
"type": "Visa",
"updated": 1559850682
},
"created": 1559131926,
"id": "2974107",
"object": "user_vendor",
"reload_amount": 10.00,
"reload_threshold": 5.00,
"role": {},
"status": {},
"updated": 1559914525,
"user": {},
"vendor": {}
}
Update auto reload settings
This request updates the user's automatic reload settings, by enabling.disabling the reload feature or by updating the amount and/or threshold values.
To turn auto-reload on, the user must supply the id of a valid billing profile, specify the amount to reload each time, and indicate the point they would like the account to reload. When "on", if the user's quickpay balance goes below the indicated threshold, auto-reload removes the specified amount from the billing profile and adds it to the user's quickpay balance.
To turn auto-reload off, the user-billingprofile must be set to null.
Query parameters
- Name
session_key- Type
- string
- Description
Session token for an end-customer.
Required attributes
- Name
user_billingProfile_id- Type
- integer
- Description
The user's billing profile to be used with automatic reload, "null" turns auto-reload off.
- Name
amount- Type
- float
- Description
How much the user would like to add to their account during an automatic reload, must be greater than 0.
- Name
threshold- Type
- float
- Description
The point at which the user's would like their account to automatically reload.
Response attributes
- Name
card- Type
- string
- Description
Returns the first and last 4 digits of the credit card number linked to this profile.
- Name
created- Type
- integer
- Description
The date this billing profile was created, listed as a Unix timestamp in seconds from 1970-01-01 00:00:00.
- Name
expiry- Type
- integer
- Description
The expiry date found on this card, listed as a Unix timestamp in seconds from 1970-01-01 00:00:00.
- Name
id- Type
- integer
- Description
An internal reference number that identifies this billing profile.
- Name
name- Type
- string
- Description
User specific card reference, as it was entered in the description when the card was added.
- Name
type- Type
- string
- Description
Indicates the type of card in a way that is user friendly.
- Name
reload_amount- Type
- float
- Description
How much the user would like to add to their account during an automatic reload, must be greater than 0.
- Name
reload_threshold- Type
- float
- Description
The point at which the user would like their account to automatically reload.
Request
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
}'
Response
{
"billing_profile": {
"card": "4242 xxxx xxxx 4242",
"created": 1562871344,
"expiry": 1564531200,
"id": "69235",
"name": "nickname",
"object": "user_billingprofile",
"type": "Visa"
},
"created": 1559131926,
"id": "2974107",
"object": "user_vendor",
"reload_amount": 10.00,
"reload_threshold": 5.00
}
Reload an account
This request is called when a user attempts to reload their account. Once a billing profile and amount are supplied, this amount is charged to the billing profile and is loaded onto the user's account in the form of quickpay currency.
Sometimes, the 3rd party service "3D Secure" will require that the user authorize their card with them. This service is designed to be an extra layer of security which protects both vendors and users from fraud. The user will be redirected to the url that is returned in the response for this request, where they must authenticate their card with the 3rd party. When this occurs, the transaction_status will have a status of pending, until the user satisfies the 3D secure authorization.
Query parameters
- Name
session_key- Type
- string
- Description
Session token for an end-customer.
Required attributes
- Name
user_billingProfile_id- Type
- integer
- Description
The user's billing profile to be used with automatic reload, "null" turns auto-reload off.
- Name
amount- Type
- float
- Description
The amount that is to be charged to this billing profile and loaded onto the user's account.
Response attributes
- Name
redirect_url- Type
- string or null
- Description
The url that redirects to the 3rd party authentication page, only necessary when authentication of the card is required.
- Name
transaction- Type
- object
- Description
An object that holds information about the reload transaction that just occurred.
- Name
amount- Type
- float
- Description
The amount that was charged from this billing profile and loaded to this account.
- Name
transaction_type- Type
- object
- Description
An object that holds information about the type of transaction that just occurred.
- Name
transaction_status- Type
- object
- Description
An object that holds information about the transaction's current status.
- Name
date- Type
- integer
- Description
The date this transaction occurred, listed as a Unix timestamp in seconds from 1970-01-01 00:00:00.
Request
curl -G https://api.spoonity.com/user/billing-profile/reload?session_key={session_key} \
-d '{
"user_billingprofile": 69206,
"amount": 15
}'
Response
{
"object": "transaction_detail",
"redirect_url": null,
"transaction": {
"object": "transaction",
"id": "20721058"
},
"amount": 15,
"transaction_type": {
"object": "transactiontype",
"id": 1,
"name": "Purchase"
},
"transaction_status": {
"object": "transactionstatus",
"id": 4,
"name": "Complete"
},
"date": 1559737276
}
Retrieve status of a reload
This endpoint allows you to retrieve the status of a reload via a transaction ID.
Query parameters
- Name
session_key- Type
- string
- Description
Session token for an end-customer.
- Name
transaction- Type
- integer
- Description
Passed in using query parameters, the internal reference number for the transaction for which the status is being checked.
Response attributes
- Name
status- Type
- string
- Description
Indicates the status of authentication with 3D Secure.
Possible status values
- Name
cancelled- Description
The user cancelled the authorization, or the authorization request timed-out and was cancelled by 3D Secure.
- Name
consumed- Description
The authorization was successful and the reload charge went through to the user's account.
- Name
failed- Description
The user entered wrong information and the authorization failed.
- Name
pending- Description
The system is waiting for the user to attempt authenticating their account.
Request
curl -G https://api.spoonity.com/user/billing-profile/reload/status?session_key={session_key}&transaction={transaction_id}
Response
{
"status": "pending"
}