Paymentwall website uses cookies to store your browsing preferences on your device. However, cookies do not collect personal information.

For more information about how we use cookies, check our cookie policy



New Documentation Getting Started API Libraries APIs Checklists Flows Integrations Mobile SDKs Reference Smart TV SDK SpiderPipe Testing Payments
If you still have questions regarding integration, please email us at

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

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:

ParameterPossible valuesDescriptionExample
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:


Request URL:

Request Parameters:

ParameterRequiredPossible valuesDescriptionExample
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
email yes string Email of the end-user. Paymentwall will automatically send a payment / offer completion receipt to the user.
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.

ag_type yes
  • fixed
  • subscription
subscription type is used for time based products, e.g. 3 month membership;
fixed is used for one-time payments, like lifetime membership.
ag_period_length yes* numeric

Length of product period, e.g. 3. Required when ag_type is subscription.

ag_period_type yes*
  • year
  • month
  • week
  • day

Type of product period. Required when ag_type is subscription.

ts yes numeric, Unix timestamp

Time when request was initiated, represented as Unix
timestamp - seconds since the Unix epoch (January 1 1970
00:00:00 GMT).


cc_token yes hexadecimal, 32 characters long

Credit card token (Returned in Pingback request)


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.


user_ip yes IPv4, dotted decimal

IP address of the end-user

user_agent yes string

User-Agent of the user

Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; WOW64; Trident/5.0)2011-10-16 20:21:07


JSON string of the following format:

ParameterPossible valuesDescriptionExample

Possible values:

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


Request URL:

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.

This page needs JavaScript
Your browser is
not supported anymore.
Please update to the more recent one.
This page needs JavaScript
This page needs JavaScript.
Please enable it in your browser settings and try again.
We use cookies on this website to make your browsing experience better. By using the Paymentwall website you agree to our Cookie Policy.