CCV Pay app: Third party integration

About

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.

Changelog

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

ccvpay://www.ccvmini.be/{type}/{currency}/{amount}/{timestamp}/{parent}/{mref}/{email}/{callback}

  • 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 test@test.com VARCHAR(255)
{callback} Optional Callback URL myapp://www.myapp.be/callback/{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://www.ccvmini.be/sale/EUR/120000.55

A refund payment of EUR 120.000,55:

  • ccvpay://www.ccvmini.be/refund/EUR/120000.55

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://www.ccvmini.be/void/EUR/null/null/58

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 test@test.com and callback URL myapp://www.myapp.be/callback/{status}:

  • ccvpay://www.ccvmini.be/sale/EUR/120000.55/1461765983000/null/My%20example%20reference/test%40test.com/myapp%3A%2F%2Fwww.myapp.be%2Fcallback%2F%7Bstatus%7D

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)

Examples:

  • Callback URL used:
    • myapp://www.myapp.be/callback/{status}/{cardholdername}/{longitude}/{latitude}
  • After a successful payment with cardholder JAN JANSSENS:
    • myapp://www.myapp.be/callback/success/JAN%20JANSSENS/37.4005502611301/-5.98233461380005
  • After a failed payment:
    • myapp://www.myapp.be/callback/failed/null/null/null

Getting started

iOS

NSString *urlString = @"ccvpay://www.ccvmini.be/sale/EUR/50.55";
NSURL *ccvPayAppUrl = [NSURL URLWithString: urlString];
BOOL success = [[UIApplication sharedApplication] openURL: ccvPayAppUrl];

Android

Uri uri = Uri.parse("ccvpay://www.ccvmini.be/sale/EUR/20.21");

Intent intent = new Intent(Intent.ACTION_VIEW);
intent.setData(uri);
intent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);

if (intent.resolveActivity(getPackageManager()) != null) {
    startActivity(intent);
}

Web

HTML

<a href="ccvpay://www.ccvmini.be/refund/EUR/1.22">CCV Pay</a>

JavaScript

window.location = "ccvpay://www.ccvmini.be/refund/EUR/1.22";

Notes

  • 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.