Documentation
Direct Billing extension
This document describes Direct Billing extension for Digital Goods API.
This extension allows merchants to bill credit cards of customers based on merchants' own schedule using credit card tokens generated by Paymentwall. For example, if virtual currency balance of the user is running low, the user can be rebilled in a pay-as-you-go manner.
This extension only changes the pingback format comparing to Digital Goods API and provides a new request type - Direct Billing, that allows to bill customers automatically using credit card tokenization.
This extension can be activated per request. For any questions, please email devsupport@paymentwall.com
End-user Experience
If the extension is activated, an additional checkbox will appear in the credit card form: "I agree to allow the owner of this site to automatically charge my account when my balance is low or when I request new features."
Changes on Pingback Processing
Additional Pingback Parameters:
| Parameter | Possible values | Description | Example |
|---|---|---|---|
| cc_token | hexadecimal, 32 characters long | Credit card token | abcdef12345678900987654321abcdef |
| cc_token_deleted | numeric | Communicates whether the credit card token is deleted and thus can not be used anymore. Upon receiving 1 the merchant should stop using the given token. | 1 |
| direct_billing_amount | numeric, with . as decimal delimiter | The amount for which the user authorizes the merchant to do direct billing | 4.99 |
| direct_billing_currency_code | ISO 4217 | USD |
- If a user ticks the checkbox, a unique credit card token will be sent in cc_token parameter of the pingback request after the user makes a payment.
- For every new payment with the checkbox being checked the pingback request will contain the credit card token.
- If a user makes a new payment and unticks the checkbox, the credit card token will be deleted, and a new parameter, cc_token_deleted=1 will be passed in the pingback. The credit card token will be sent in the pingback request in this case one more last time so that the merchant can delete this token from his database.
- Later, if a user makes a new payment and ticks the checkbox again, the old token will be re-activated and sent through the cc_token parameter in the pingback request.
Direct Billing
Billing Request
Request Method:
HTTPS GET
Request URL:
https://api.paymentwall.com/api/cc/direct-billing
Request Parameters:
| Parameter | Required | Possible values | Description | Example |
|---|---|---|---|---|
| key | yes | hexadecimal, 32 characters long | Project key | abcdef12345678900987654321abcdef |
| uid | yes | alphanumeric, up to 64 characters long | ID of the end-user in your system who is being charged. Examples: numeric ID, username or email | user12345 |
| widget | yes | p1 | p1 | |
| amount | yes | numeric, with . as decimal delimiter | Amount of the purchase | 10.00 |
| currencyCode | yes | ISO 4217 | Currency of the purchase, e.g. USD, EUR | USD |
| yes | string | Email of the end-user. Paymentwall will automatically send a payment / offer completion receipt to the user. | username@example.com | |
| ag_name | yes | alphanumeric, up to 256 characters long | Product name | 100 Credits |
| ag_external_id | yes | alphanumeric, up to 256 characters long |
Alphanumeric ID of the product in your system, which we communicate back to you via the pingback as goodsid parameter. |
100_credits |
| ag_type | yes |
|
subscription type is used for time based products, e.g. 3 month membership; fixed is used for one-time payments, like lifetime membership. |
fixed |
| ag_period_length | yes* | numeric |
Length of product period, e.g. 3. Required when ag_type is subscription. |
1 |
| ag_period_type | yes* |
|
Type of product period. Required when ag_type is subscription. |
month |
| ts | yes | numeric, Unix timestamp |
Time when request was initiated, represented as Unix |
1349067600 |
| cc_token | yes | hexadecimal, 32 characters long |
Credit card token (Returned in Pingback request) |
abcdef12345678900987654321abcdef |
| sign_version | yes | 2 | Version of signature. sign_version=2 needs to be used | 2 |
| sign | yes | hexadecimal, 32 characters long, lowercase |
Request signature. For detailed info on signature calculation please refer to Signature Calculation documentation. |
abcdef12345678900987654321abcdef |
| user_ip | yes | IPv4, dotted decimal |
IP address of the end-user |
255.255.255.255 |
| user_agent | yes | string |
User-Agent of the user |
E.g. |
Response:
JSON string of the following format:
{"result":$result,"message":$message,"code":$code}
| Parameter | Possible values | Description | Example |
|---|---|---|---|
| $result |
Possible values:
|
Result of the request | OK |
| $message | string | Optional message. Empty if $result is OK. Contains error message if there is an error. | Incorrect request signature |
| $code | int | Optional error code. Empty if $result is OK. Contains error code if there is an error |
Direct Billing Test Mode
Billing Request
Request Method:
HTTPS GET
Request URL:
https://api.paymentwall.com/api/dummy/direct-billing
In order to test direct billing API, please use the same parameters mentioned above.
To generate a test token you can use Test Payment method or Test Pingback tool.
