CCV Pay app: Third party integration


It’s possible to launch CCV Pay and start a payment flow directly from your own app. The payment information needed, is transferred to CCV Pay in the form of an URL.


  • V1.2 Specified type for each field
  • V1.1 Added callback mechanism and appropriate parameters
  • V1.0 Initial specification

URL format

The URL has the following format:


  • All parameters must be URL-encoded.
  • Optional values that are not used must always use the keyword null.
  • Optional values at the end of the URL may be omitted and will be treated as null.
  • Required values may not be null.

The parameters have the following format:

Parameter Type Description Example Type
{type} Required Type of the transaction sale Enum: sale, refund, void
{currency} Conditional Currency as defined in ISO 4217. Required during a sale or refund, ignored during a void. EUR VARCHAR(3)
{amount} Conditional A strict positive decimal number with a . as decimal separator. Must have exact decimal numbers as dictated by the currency. Required during a sale or refund, ignored during a void. 12.34 VARCHAR(255)
{timestamp} Optional Transaction timestamp in milliseconds 1461765983000 VARCHAR(255)
{parent} Conditional Transaction id of parent, required in case of void type 80119063-CB48-485E-BA29-45076C300387 VARCHAR(255)
{mref} Optional Merchant reference description My example reference VARCHAR(20)
{email} Optional Customer receipt email VARCHAR(255)
{callback} Optional Callback URL myapp://{status} VARCHAR(512)

The transaction timestamp can be used to identify the transaction request and it prevents a transaction from being started twice. You can also use it to perform a status check on a previously iniated transaction. If the timestamp is already found during transaction processing, it will not initiate a new transaction but it will still trigger the callback URL if specified.

Some examples:

A sale payment of EUR 120.000,55:

  • ccvpay://

A refund payment of EUR 120.000,55:

  • ccvpay://

A void of a previous payment with transaction id 58. The currency has been filled in but will be ignored and can be replaced with “null”:

  • ccvpay://

A sale payment of EUR 120.000,55 at timestamp Wed, 27 Apr 2016 14:06:23 GMT with merchant reference My example reference, email and callback URL myapp://{status}:

  • ccvpay://

Callback URL format

The callback URL will have the following keywords replaced:

Parameter Description Example Type
{status} Transaction status success Enum: success, failed
{id} Transaction id 58 VARCHAR(255)
{authorisationcode} Authorisation code HQx720 VARCHAR(255)
{cardholdername} Cardholder name Jan Janssens VARCHAR(255)
{longitude} GPS longitude coordinate 37.4005502611301 VARCHAR(255)
{latitude} GPS latitude coordinate -5.98233461380005 VARCHAR(255)


  • Callback URL used:
    • myapp://{status}/{cardholdername}/{longitude}/{latitude}
  • After a successful payment with cardholder JAN JANSSENS:
    • myapp://
  • After a failed payment:
    • myapp://

Getting started


NSString *urlString = @"ccvpay://";
NSURL *ccvPayAppUrl = [NSURL URLWithString: urlString];
BOOL success = [[UIApplication sharedApplication] openURL: ccvPayAppUrl];


Uri uri = Uri.parse("ccvpay://");

Intent intent = new Intent(Intent.ACTION_VIEW);

if (intent.resolveActivity(getPackageManager()) != null) {



<a href="ccvpay://">CCV Pay</a>


window.location = "ccvpay://";


  • When the merchant isn’t logged in, the app will launch and just show the login screen. A payment flow will not be started.
  • When a payment flow is currently happening, the app is just brought to the foreground and the existing flow will continue.