NAV Navbar
cURL PHP Java

Introduction

PHP library covers all the functionality provided by Cardinity API. 

Library source code and releases can be obtained from GitHub: 
https://github.com/cardinity/cardinity-sdk-php

Installing via Composer:
$ php composer.phar require cardinity/cardinity-sdk-php

Bundle for Symfony2 project is also available:
https://github.com/cardinity/client-bundle
Java library covers all the functionality provided by Cardinity API. 

Library source code and releases can be obtained from GitHub: 
https://github.com/cardinity/cardinity-sdk-java

Cardinity API is organized around REST. OAuth 1.0 is used as the API Authentication framework. Request and response payloads are formatted as JSON. Error details are also provided as JSON. API uses resource-oriented URLs and HTTP response codes to indicate API errors and successful actions.

Authentication

Authentication Example

<?php

/** 
* You don't have to bother about authentication. 
* It is handled auto-magically behind the scenes.
* You just have to initialize the client object. 
*/
use Cardinity\Client;
$client = Client::create([
    'consumerKey' => 'YOUR_CONSUMER_KEY',
    'consumerSecret' => 'YOUR_CONSUMER_SECRET',
]);

?>
/** 
* You don't have to bother about authentication. 
* It is handled auto-magically behind the scenes.
* You just have to initialize the client object. 
*/
CardinityClient client = new CardinityClient(consumerKey, consumerSecret);
# With cURL, you need to pass the correct header with each request

curl https://api.cardinity.com/v1/<endpoint> \
  -H "Content-Type: application/json" \
  -H 'Authorization: OAuth oauth_consumer_key="<your_consumer_key>", \
      oauth_signature_method="HMAC-SHA1", \
      oauth_timestamp="<timestamp>", \
      oauth_nonce="<unique_random_string>", \
      oauth_version="1.0", \
      oauth_signature="<computed_oauth_signature>"'

Cardinity uses OAuth 1.0 to authorize all API requests. 0-legged (sometimes called 1-legged) OAuth scheme is used. Picture below describes basics of an authorization flow using 0-legged OAuth.

To learn more about OAuth you can visit: OAuth Bible, The OAuth 1.0 Protocol.

alt 0-legged

Cardinity expects for the OAuth details to be included in all API requests to the server in a header that looks like the following:

Authorization: OAuth {OAUTH_DETAILS}

OAuth Parameters

Name Description
oauth_consumer_key Identifier string provided by Cardinity for use in OAuth 1.0 handshake. Equivalent to a username.
oauth_signature_method Always HMAC-SHA1.
oauth_timestamp Timestamp when the request was generated. Timestamp is valid for 5 minutes.
oauth_nonce Uniquely generated random string. Recommended length 32 characters.
Note: same value can not be used more than once.
oauth_version Always 1.0.
oauth_signature String made up of Request Method, URL and Parameters joined in a single string which is then encrypted against your Consumer Secret.
Note: request body is not included in a signature string.
oauth_token Can be omitted. Otherwise left blank.

Testing

You'll receive special Consumer Key and Consumer Secret for the testing environment. Endpoint URLs are the same as used in production. All the payments made in testing environment never hit real bank networks, so card is never charged.

Testing Cards

Basically you can use any valid VISA or MasterCard card number, however for your convenience we provide sample ones you can use:

Number Brand
4111111111111111 Visa
4222222222222 Visa
5555555555554444 MasterCard

holder, exp_month, exp_year, cvc values can be set to any data you want. If those values passes validation and payment amount is less than 150.00 payment will be approved.

Test Cases

There is a variety of test cases which you can use to validate your integration with Cardinity payment processing gateway.

Successful Payment

Failed Payment

3D Secure Payment

Failed refund / void / settlement

Payments

To process a payment you have to create a new payment object. You can retrieve individual payments as well as a list of all payments. Payments are identified by a UUID.

Payment Object

Example: Approved Payment JSON

{
    "id": "90095d47-11bb-468b-8764-fd4fbb49a9f9",
    "amount": "15.00",
    "currency": "EUR",
    "created": "2014-12-19T11:52:53Z",
    "type": "authorization",
    "live": false,
    "status": "approved",
    "order_id": "123456",
    "description": "some description",
    "country": "LT",
    "payment_method": "card",
    "payment_instrument": {
        "card_brand": "Visa",
        "pan": "0026",
        "exp_year": 2021,
        "exp_month": 12,
        "holder": "Mike Dough"
    }
}

Example: Pending Payment JSON

{
    "id": "8e037fbb-fe5b-4781-b109-b3e93d5f2c0d",
    "amount": "20.00",
    "currency": "EUR",
    "created": "2014-12-17T09:43:31Z",
    "type": "authorization",
    "live": false,
    "status": "pending",
    "order_id": "1234567",
    "description": "some description",
    "country": "LT",
    "payment_method": "card",
    "payment_instrument": {
        "card_brand": "Visa",
        "pan": "4447",
        "exp_year": 2017,
        "exp_month": 5,
        "holder": "John Smith"
    },
    "authorization_information": {
        "url": "https://authorization.url/auth",
        "data": "eJxdUl1vwj......."
    }
}

Example Declined Payment JSON

{
    "id": "3c4e8dcf-4e3e-4df0-9acb-622868c6c67b",
    "amount": "150.00",
    "currency": "EUR",
    "created": "2015-01-07T12:23:11.569Z",
    "type": "authorization",
    "live": false,
    "status": "declined",
    "error": "3000: Do not Honor",
    "country": "LT",
    "order_id": "12345678",
    "description": "some description",
    "payment_method": "card",
    "payment_instrument": {
        "card_brand": "Visa",
        "pan": "0067",
        "exp_year": 2021,
        "exp_month": 11,
        "holder": "Mike Dough"
    }
}

Attributes

Name Type Description
id UUID ID of the payment.
Value assigned by Cardinity.
amount decimal Amount charged shown in #0.00 format.
currency string Three-letter ISO currency code representing the currency in which the charge was made. Supported currencies: EUR, GBP, USD.
created datetime Payment creation time as defined in RFC 3339 Section 5.6. UTC timezone.
Value assigned by Cardinity.
type string Payment type. Can be one of the following: authorization, purchase.
Value assigned by Cardinity.
live boolean Indicates whether a payment was made in live or testing mode.
Value assigned by Cardinity.
settle boolean Optional. Default: true.
Used to indicate a transaction type while creating a payment: true - purchase, false - authorization.
status string Payment status. Can be one of the following: pending, approved, declined.
Value assigned by Cardinity.
error string Error message. Returned only if status is declined. Provides human readable information why the payment failed.
Value assigned by Cardinity.
order_id string Optional. Order ID provided by a merchant. Must be between 2 and 50 characters [A-Za-z0-9'.-].
description string Payment description provided by a merchant. Maximum length 255 characters.
country string Country of a customer provided by a merchant. ISO 3166-1 alpha-2 country code.
payment_method string Can be one the following: card, recurring.
payment_instrument object Payment instrument representing earlier described payment_method. Can be one of the following: card or recurring. See object descriptions below.
authorize_data string Used to provide additional information (PATCH verb) once customer completes authorization process.
authorization_information object Specific authorization object returned in case additional payment authorization is needed (i.e. payment status is pending). See object description below.
Value assigned by Cardinity.

Payment Instrument - card

Name Type Description
brand string Card brand.
Value assigned by Cardinity.
pan string Card number. When creating a payment provide full card number. However while retrieving an existing payments only last 4 digits are returned.
exp_year integer Expiration year. 4 digits, e.g. 2021.
exp_month integer Expiration month, e.g. 9.
cvc string Card security code. Only used when creating a payment.
holder string Card holder's name. Max length 32 characters.

Payment Instrument - recurring

Name Type Description
payment_id UUID Id of the approved payment in the past. Same card data will be used to create a new payment.

Authorization Information

Name Type Description
url string URL where customer should be redirected to complete a payment authorization.
Value assigned by Cardinity.
data string Data which must be passed along with the customer being redirected.
Value assigned by Cardinity.

3D Secure Program

Example: 3D Secure Redirection Page

<html>
   <head>
      <title>3-D Secure Example</title>
      <script type="text/javascript">
          function OnLoadEvent()
          {
            // Make the form post as soon as it has been loaded.
            document.theForm.submit();
          }
      </script>
   </head>
   <body onload="OnLoadEvent();">
      <p>
          If your browser does not start loading the page,
          press the button below.
          You will be sent back to this site after you
          authorize the transaction.
      </p>
      <form name="ThreeDForm" method="POST" action="{url}">
          <button type=submit>Click Here</button>
          <input type="hidden" name="PaReq" value="{data}" />
          <input type="hidden" name="TermUrl" value="{your_callback_url}" />
          <input type="hidden" name="MD" value="{your_identifier}" />
      </form>
   </body>
</html>

If you have 3D Secure enabled for your account additional steps to authorize a payment might be needed. 3D Secure flow is described below.

3D Secure Flow

alt 3D Secure Flow

3D Secure Integration Steps

  1. Create a new payment as usual.
  2. If the returned payment object has status: pending (response code: 202) 3D Secure authorization is required.
  3. Returned payment object will also have authorization_information attribute assigned. Grab url and data attributes from authorization_information object and initiate customer's redirect to the ACS:
    • You need to create a special POST redirect page and serve it to a customer. Example can be seen on the right.
    • Set PaReq parameter to data attribute received in authorization_information object.
    • Set Form action parameter to url attribute received in authorization_information object.
    • Set TermUrl to your callback url which will receive information from ACS when buyer completes authorization.
    • Set MD to your unique identifier allowing you to map callback to the exact payment request.
  4. Once customer finalizes authorization you'll receive callback to the TermUrl you've provided earlier. It will contain two parameters:
    • MD: your unique identifier echoed back.
    • PaRes: payer authentication response.
  5. Send a PATCH request to Cardinity as described in Finalize Pending Payment providing PaRes parameter data received from ACS as authorize_data attribute.
  6. Cardinity will finalize the payment and return back it's result.

Create new payment

Example Request

<?php

use Cardinity\Client;
use Cardinity\Method\Payment;
use Cardinity\Exception;

$client = Client::create([
    'consumerKey' => 'YOUR_CONSUMER_KEY',
    'consumerSecret' => 'YOUR_CONSUMER_SECRET',
]);

$method = new Payment\Create([
    'amount' => 50.00,
    'currency' => 'EUR',
    'settle' => false,
    'description' => 'some description',
    'order_id' => '12345678',
    'country' => 'LT',
    'payment_method' => Payment\Create::CARD,
    'payment_instrument' => [
        'pan' => '4111111111111111',
        'exp_year' => 2021,
        'exp_month' => 12,
        'cvc' => '456',
        'holder' => 'Mike Dough'
    ],
]);

/** 
* In case payment could not be processed exception will be thrown. 
* In this example only Declined exception is handled. However there is more of them.
* See Error Codes section for detailed list.
*/
try {
    /** @type Cardinity\Method\Payment\Payment */
    $payment = $client->call($method);
} catch (Exception\Declined $exception) {
    /** @type Cardinity\Method\Payment\Payment */
    $payment = $exception->getResult();
    $status = $payment->getStatus(); // value will be 'declined'
    $errors = $exception->getErrors(); // list of errors occured
}

?>
CardinityClient client = new CardinityClient(consumerKey, consumerSecret);

Payment payment = new Payment();
payment.setAmount(new BigDecimal(10));
payment.setCurrency("EUR");
payment.setCountry("LT");
payment.setPaymentMethod(Payment.Method.CARD);
Card card = new Card();
card.setPan("4111111111111111");
card.setCvc(123);
card.setExpYear(2021);
card.setExpMonth(1);
card.setHolder("John Doe");
payment.setPaymentInstrument(card);

Result<Payment> result = client.createPayment(payment);

/** Request was valid and payment was approved. */
if (result.isValid() && result.getItem().getStatus() == Payment.Status.APPROVED) {
    UUID paymentId = result.getItem().getId();
    // proceed with successful payment flow
}

/** Request was valid but payment requires additional authentication. */
else if (result.isValid() && result.getItem().getStatus() == Payment.Status.PENDING) {
    UUID paymentId = result.getItem().getId();
    String acsURL = result.getItem().getAuthorizationInformation().getUrl();
    String paReq = result.getItem().getAuthorizationInformation().getData();
    // redirect customer to ACS server for 3D Secure authentication
}

/** Request was valid but payment was declined. */
else if (result.isValid()) {
    String declineReason = result.getItem().getError();
    // proceed with declined payment flow
}

/** Request was invalid. Possible reasons: wrong credentials, unsupported currency, suspended account, etc. */
else {
    CardinityError error = result.getCardinityError();
    // log error details for debugging 
    // proceed with error handling flow
}
curl https://api.cardinity.com/v1/payments \
-H "Content-Type: application/json" \
-H "Authorization: OAuth <OAuth Details>" \
-d '{
    "amount": "50.00",
    "currency": "EUR",
    "settle": false,
    "description": "some description",
    "order_id": "12345678",
    "country": "LT",
    "payment_method": "card",
    "payment_instrument": {
        "pan": "4111111111111111",
        "exp_year": 2021,
        "exp_month": 11,
        "cvc": "999",
        "holder": "Mike Dough"
    }
}'

# Response JSON
{
    "id": "90095d47-11bb-468b-8764-fd4fbb49a9f9",
    "amount": "50.00",
    "currency": "EUR",
    "created": "2014-12-19T11:52:53Z",
    "type": "authorization",
    "live": false,
    "status": "approved",
    "order_id": "12345678",
    "description": "some description",
    "country": "LT",
    "payment_method": "card",
    "payment_instrument": {
        "card_brand": "Visa",
        "pan": "1111",
        "exp_year": 2021,
        "exp_month": 11,
        "holder": "Mike Dough"
    }
}

To process a payment you have to create a new payment object. If your API Consumer Key key is in a test mode the supplied card won't be charged, though everything else will occur as if in a live mode.

HTTP Request

POST https://api.cardinity.com/v1/payments

Request Attributes

Name Type Required Description
amount decimal Yes Amount to charge. Only positive values are allowed. Format: #0.00, two decimal places precision is required.
currency string Yes Three-letter ISO currency code representing the currency of the amount. Supported currencies: EUR, GBP, USD.
settle boolean No Default: true.
Indicates payment type: true - purchase, false - authorization. Purchase encapsulates authorization and settlement steps in one action.
order_id string No Order ID provided by a merchant. Must be between 2 and 50 characters [A-Za-z0-9'.-].
description string No Payment description provided by a merchant. Maximum length 255 characters.
country string Yes Country of a customer obtained via geolocation services or entered manually. ISO 3166-1 alpha-2 country code.
payment_method string Yes Can only be: card.
payment_instrument object Yes Payment instrument representing earlier described payment_method. For now only card is supported. See object description below.

Payment Instrument - card

Name Type Required Description
pan string Yes Card number.
exp_year integer Yes Expiration year. 4 digits.
exp_month integer Yes Expiration month.
cvc string Yes Card security code.
holder string Yes Card holder's name. Max length 32 characters.

Response

Returns a payment object if:

Returns an error object otherwise. Response codes: 400, 401, 405, 500, 503.

If a payment is in a pending state (status: pending) additional authorization_information attribute is provided. Merchant must use provided information to redirect customer for an additional payment authorization steps. See: 3D Secure Program and Finalize Pending Payment

If a payment was declined (status: declined) payment object contains error attribute explaining why this happened. A common reason for payment being declined is an invalid or expired card, or a valid card with insufficient available balance.

Create recurring payment

Example Request

<?php

use Cardinity\Client;
use Cardinity\Method\Payment;
use Cardinity\Exception;

$client = Client::create([
    'consumerKey' => 'YOUR_CONSUMER_KEY',
    'consumerSecret' => 'YOUR_CONSUMER_SECRET',
]);

$method = new Payment\Create([
    'amount' => 50.00,
    'currency' => 'EUR',
    'settle' => false,
    'description' => 'some description',
    'order_id' => '12345678',
    'country' => 'LT',
    'payment_method' => Payment\Create::RECURRING,
    'payment_instrument' => [
        'payment_id' => $paymentId
    ],
]);

/** 
* In case payment could not be processed exception will be thrown. 
* In this example only Declined exception is handled. However there is more of them.
* See Error Codes section for detailed list.
*/
try {
    /** @type Cardinity\Method\Payment\Payment */
    $payment = $client->call($method);
} catch (Exception\Declined $exception) {
    /** @type Cardinity\Method\Payment\Payment */
    $payment = $exception->getResult();
    $status = $payment->getStatus(); // value will be 'declined'
    $errors = $exception->getErrors(); // list of errors occured
}

?>
CardinityClient client = new CardinityClient(consumerKey, consumerSecret);

Payment payment = new Payment();
payment.setAmount(new BigDecimal(10));
payment.setCurrency("EUR");
payment.setCountry("LT");
payment.setPaymentMethod(Payment.Method.RECURRING);
Recurring recurringPayment = new Recurring();
// set to ID of a previous payment
recurringPayment.setPaymentId(previousPaymentId);
payment.setPaymentInstrument(recurringPayment);

Result<Payment> result = client.createPayment(payment);

/** Request was valid and payment was approved. */
if (result.isValid() && result.getItem().getStatus() == Payment.Status.APPROVED) {
    UUID paymentId = result.getItem().getId();
    // proceed with successful payment flow
}

/** Request was valid but payment was declined. */
else if (result.isValid()) {
    String declineReason = result.getItem().getError();
    // proceed with declined payment flow
}

/** Request was invalid. */
else {
    CardinityError error = result.getCardinityError();
    // log error details for debugging 
    // proceed with error handling flow
}
curl https://api.cardinity.com/v1/payments \
-H "Content-Type: application/json" \
-H "Authorization: OAuth <OAuth Details>" \
-d '{
    "amount": "50.00",
    "currency": "EUR",
    "settle": false,
    "description": "some description",
    "order_id": "12345678",
    "country": "LT",
    "payment_method": "recurring",
    "payment_instrument": {
        "payment_id": "ba3119f2-9a73-11e4-89d3-123b93f75cba"
    }
}'

# Response JSON
{
    "id": "ba31174a-9a73-11e4-89d3-123b93f75cba",
    "amount": "50.00",
    "currency": "EUR",
    "created": "2014-12-19T11:52:53Z",
    "type": "authorization",
    "live": false,
    "status": "approved",
    "order_id": "12345678",
    "description": "some description",
    "country": "LT",
    "payment_method": "card",
    "payment_instrument": {
        "card_brand": "Visa",
        "pan": "1111",
        "exp_year": 2021,
        "exp_month": 11,
        "holder": "Mike Dough"
    }
}

To process a recurring payment you have to create a new payment object with payment_method attribute set to recurring and provide ID of the previous successful payment in a payment_instrument object. Same card will be used to create a new payment.

HTTP Request

POST https://api.cardinity.com/v1/payments

Request Attributes

Name Type Required Description
amount decimal Yes Amount to charge. Only positive values are allowed. Format: #0.00, two decimal places precision is required.
currency string Yes Three-letter ISO currency code representing the currency of the amount. Supported currencies: EUR, GBP, USD.
settle boolean No Default: true.
Indicates payment type: true - purchase, false - authorization. Purchase encapsulates authorization and settlement steps in one action.
order_id string No Order ID provided by a merchant. Must be between 2 and 50 characters [A-Za-z0-9'.-].
description string No Payment description provided by a merchant. Maximum length 255 characters.
country string Yes Country of a customer obtained via geolocation services or entered manually. ISO 3166-1 alpha-2 country code.
payment_method string Yes Can only be: recurring.
payment_instrument object Yes Payment instrument representing earlier described payment_method. See object description below.

Payment Instrument - recurring

Name Type Required Description
payment_id string Yes ID of the successful payment in the past.

Response

Returns a payment object if:

Returned payment object contains payment_instrument which was used in the initial payment.

Returns an error object otherwise. Response codes: 400, 401, 405, 500, 503.

If a payment was declined (status: declined) payment object contains error attribute explaining why this happened. A common reason for payment being declined is an invalid or expired card, or a valid card with insufficient available balance.

Finalize pending payment

Example Request

<?php

use Cardinity\Client;
use Cardinity\Method\Payment;

$client = Client::create([
    'consumerKey' => 'YOUR_CONSUMER_KEY',
    'consumerSecret' => 'YOUR_CONSUMER_SECRET',
]);

$method = new Payment\Finalize($payment->getId(), 'PARES_RECEIVED_FROM_ACS');
/** @type Cardinity\Method\Payment\Payment */
$payment = $client->call($method);

?>
CardinityClient client = new CardinityClient(consumerKey, consumerSecret);

/**
 * paymentId - ID of a pending payment
 * paRes - data received from ACS 
 */
Result<Payment> result = client.finalizePayment(paymentId, paRes);

/** Request was valid and payment was approved. */
if (result.isValid() && result.getItem().getStatus() == Payment.Status.APPROVED) {
    UUID paymentId = result.getItem().getId();
    // proceed with successful payment flow
}

/** Request was valid but payment was declined. */
else if (result.isValid()) {
    String declineReason = result.getItem().getError();
    // proceed with declined payment flow
}

/** Request was invalid. */
else {
    CardinityError error = result.getCardinityError();
    // log error details for debugging 
    // proceed with error handling flow
}
curl --request PATCH https://api.cardinity.com/v1/payments/cb5e1c95-7685-4499-a2b1-ae0f28297b92 \
-H "Content-Type: application/json" \
-H "Authorization: OAuth <OAuth Details>" \
-d '{
    "authorize_data": "fGxdUl3451vdas.......",
}'

To finalize a pending payment you have to send a PATCH request for that payment providing only authorize_data attribute which should contain PaRes parameter data as received from 3D Secure ACS.

HTTP Request

PATCH https://api.cardinity.com/v1/payments/{PAYMENT_ID}

Response

Returns a payment object if:

Returns an error object otherwise. Response codes: 400, 401, 405, 500, 503.

If a payment was declined (status: declined) payment object contains error attribute explaining why this happened. A common reason for payment being declined is an invalid or expired card, or a valid card with insufficient available balance.

Get existing payment

Request Example

<?php

use Cardinity\Client;
use Cardinity\Method\Payment;

$client = Client::create([
    'consumerKey' => 'YOUR_CONSUMER_KEY',
    'consumerSecret' => 'YOUR_CONSUMER_SECRET',
]);

$method = new Payment\Get($payment->getId());
/** @type Cardinity\Method\Payment\Payment */
$payment = $client->call($method);

?>
CardinityClient client = new CardinityClient(consumerKey, consumerSecret);

Result<Payment> result = client.getPayment(paymentId);
if (result.isValid()) {
    Payment payment = result.getItem();
}
else {
    CardinityError error = result.getCardinityError();
}      
curl https://api.cardinity.com/v1/payments/cb5e1c95-7685-4499-a2b1-ae0f28297b92 \
  -H "Content-Type: application/json" \
  -H "Authorization: OAuth <OAuth Details>"

To retrieve a specific payment you have to send GET request providing an ID of a payment.

HTTP Request

GET https://api.cardinity.com/v1/payments/{PAYMENT_ID}

Response

Returns a payment object if payment was found. Response code: 200.

Returns an error object if payment was not found. Response code: 404.

Get all payments

Example Request

<?php

use Cardinity\Client;
use Cardinity\Method\Payment;

$client = Client::create([
    'consumerKey' => 'YOUR_CONSUMER_KEY',
    'consumerSecret' => 'YOUR_CONSUMER_SECRET',
]);

$method = new Payment\GetAll();
$result = $client->call($method);
/** @type Cardinity\Method\Payment\Payment */
$payment = $result[0];

?>
CardinityClient client = new CardinityClient(consumerKey, consumerSecret);

Result<List<Payment>> result = client.getPayments();
if (result.isValid()) {
    List<Payment> payments = result.getItem();
}
else {
    CardinityError error = result.getCardinityError();
}
curl https://api.cardinity.com/v1/payments \
  -H "Content-Type: application/json" \
  -H "Authorization: OAuth <OAuth Details>"

# Response JSON
[  
   {  
      "id": "cb5e1c95-7685-4499-a2b1-ae0f28297b92",
      "amount": "20.00",
      "currency": "EUR",
      "created": "2014-12-17T09:46:11Z",
      "type": "authorization",
      "live": false,
      "description": "some description",
      "status": "declined",
      "error": "33333: 3D Secure Authorization Failed.",
      "country": "LT",
      "payment_method": "card",
      "payment_instrument":{  
         "card_brand": "Visa",
         "pan": "0006",
         "exp_year": 2017,
         "exp_month": 5,
         "holder": "John Smith"
      }
   },
   {  
      "id": "1379c6bb-dcd9-4669-8846-85a278c2aa7f",
      "amount": "20.00",
      "currency": "EUR",
      "created": "2014-12-17T09:44:01Z",
      "type": "authorization",
      "live": false,
      "description": "some description",
      "status": "approved",
      "country": "LT",
      "payment_method": "card",
      "payment_instrument":{  
         "card_brand": "Visa",
         "pan": "4447",
         "exp_year": 2017,
         "exp_month": 5,
         "holder": "John Smith"
      }
   }
]

To retrieve all payments you have to send a GET request. An optional limit parameter can be used to specify a number of last payments to be returned. Default: 10 last payments.

HTTP Request

GET https://api.cardinity.com/v1/payments

Query Parameters

Parameter Default Description
limit 10 Number of last payments to be returned.

Response

Returns a list of payment objects. Response code: 200.

Refunds

To process a refund you have to create a new refund object. You can retrieve individual refund for a specific payment as well as a list of all refunds for a specific payment. Refunds are identified by a UUID.

Refund Object

Example: Approved Refund JSON

{  
   "id": "25e6f869-6675-4488-bd47-ccd298f74b3f",
   "amount": "0.50",
   "currency": "EUR",
   "type": "refund",
   "created": "2015-01-16T09:05:27Z",
   "live": false,
   "parent_id": "f02862aa-5dcc-4637-9ddf-b9140c2b4b06",
   "status": "approved"
}

Attributes

Name Type Description
id UUID ID of the refund.
Value assigned by Cardinity.
amount decimal Amount refunded shown in #0.00 format.
currency string Three-letter ISO currency code representing the currency in which the refund was made. Supported currencies: EUR, GBP, USD.
Value assigned by Cardinity.
type string Can only be: refund.
Value assigned by Cardinity.
created datetime Refund creation time as defined in RFC 3339 Section 5.6. UTC timezone.
Value assigned by Cardinity.
live boolean Indicates whether a refund was made in live or testing mode.
Value assigned by Cardinity.
parent_id UUID ID of the refunded payment.
Value assigned by Cardinity.
status string Refund status. Can be one of the following: approved or declined.
Value assigned by Cardinity.
error string Error message. Returned only if status is declined. Provides human readable information why a refund failed.
Value assigned by Cardinity.
order_id string Optional. Order ID provided by a merchant in initial payment. Must be between 2 and 50 characters [A-Za-z0-9'.-].
Value assigned by Cardinity.
description string Optional. Refund description provided by a merchant. Maximum length 255 characters.

Create new refund

Example Request

<?php

use Cardinity\Client;
use Cardinity\Method\Refund;

$client = Client::create([
    'consumerKey' => 'YOUR_CONSUMER_KEY',
    'consumerSecret' => 'YOUR_CONSUMER_SECRET',
]);

$method = new Refund\Create(
    $payment->getId(),
    10.00,
    'my description'
);
/** @type Cardinity\Method\Refund\Refund */
$refund = $client->call($method);

?>
CardinityClient client = new CardinityClient(consumerKey, consumerSecret);

Refund refund = new Refund(new BigDecimal(10));
Result<Refund> result = client.createRefund(paymentId, refund);

/** Request was valid and refund was approved. */
if (result.isValid() && result.getItem().getStatus() == Refund.Status.APPROVED) {
    refund = result.getItem();
    // proceed with successful refund flow
}

/** Request was valid but refund was declined. */
else if (result.isValid()) {
     String declineReason = result.getItem().getError();
     // proceed with declined refund flow
}

/** Request was invalid. */
else {
    CardinityError error = result.getCardinityError();
    // handle error
}
curl https://api.cardinity.com/v1/payments/90ebe1a8-ebaf-48c5-b654-19c8e6ae5368/refunds \
-H "Content-Type: application/json" \
-H "Authorization: OAuth <OAuth Details>" \
-d '{
    "amount": "10.00",
    "description": "some description"
}'

# Response JSON
{
   "id": "25e6f869-6675-4488-bd47-ccd298f74b3f",
   "amount": "10.00",
   "currency": "EUR",
   "type": "refund",
   "created": "2015-01-16T09:05:27Z",
   "live": false,
   "parent_id": "90ebe1a8-ebaf-48c5-b654-19c8e6ae5368",
   "status": "approved",
   "description": "some description"
}

To process a refund you have to create a new refund object providing Payment ID and amount to be refunded. Partial refunds can be made thus one payment might have more than one refund.

HTTP Request

POST https://api.cardinity.com/v1/payments/{PAYMENT_ID}/refunds

Request Attributes

Name Type Required Description
amount decimal Yes Amount to be refunded. Only positive values are allowed. Format: #0.00, two decimal places precision is required.
description string No Refund description provided by a merchant. Maximum length 255 characters.

Response

Returns a refund object if:

Returns an error object otherwise. Response codes: 400, 401, 405, 500, 503.

If a refund was declined (status: declined) refund object contains error attribute explaining why this happened.

Get existing refund

Request Example

<?php

use Cardinity\Client;
use Cardinity\Method\Refund;

$client = Client::create([
    'consumerKey' => 'YOUR_CONSUMER_KEY',
    'consumerSecret' => 'YOUR_CONSUMER_SECRET',
]);

$method = new Refund\Get(
    $payment->getId(),
    $refund->getId()
);
/** @type Cardinity\Method\Refund\Refund */
$refund = $client->call($method);

?>
CardinityClient client = new CardinityClient(consumerKey, consumerSecret);

Result<Refund> result = client.getRefund(paymentId, refundId);

if (result.isValid()) {
    Refund refund = result.getItem();
}
else {
    CardinityError error = result.getCardinityError();
} 
curl https://api.cardinity.com/v1/payments/cb5e1c95-7685-4499-a2b1-ae0f28297b92/refunds/25e6f869-6675-4488-bd47-ccd298f74b3f \
  -H "Content-Type: application/json" \
  -H "Authorization: OAuth <OAuth Details>"

To retrieve a specific refund you have to send a GET request providing an ID of a payment and ID of a refund.

HTTP Request

GET https://api.cardinity.com/v1/payments/{PAYMENT_ID}/refunds/{REFUND_ID}

Response

Returns a refund object if refund was found. Response code: 200.

Returns an error object if refund was not found. Response code: 404.

Get all refunds

Request Example

<?php

use Cardinity\Client;
use Cardinity\Method\Refund;

$client = Client::create([
    'consumerKey' => 'YOUR_CONSUMER_KEY',
    'consumerSecret' => 'YOUR_CONSUMER_SECRET',
]);

$method = new Refund\GetAll(
    $payment->getId()
);
$result = $client->call($method);
/** @type Cardinity\Method\Refund\Refund */
$refund = $result[0];

?>
CardinityClient client = new CardinityClient(consumerKey, consumerSecret);

Result<List<Refund>> result = client.getRefunds(paymentId);

if (result.isValid()) {
    List<Refund> refunds = result.getItem();
}
else {
    CardinityError error = result.getCardinityError();
}
curl https://api.cardinity.com/v1/payments/90ebe1a8-ebaf-48c5-b654-19c8e6ae5368/refunds \
  -H "Content-Type: application/json" \
  -H "Authorization: OAuth <OAuth Details>"

# Response JSON
[  
   {
       "id": "25e6f869-6675-4488-bd47-ccd298f74b3f",
       "amount": "5.00",
       "currency": "EUR",
       "type": "refund",
       "created": "2015-01-16T09:05:27Z",
       "live": false,
       "parent_id": "90ebe1a8-ebaf-48c5-b654-19c8e6ae5368",
       "status": "approved",
       "description": "some description"
   },
   {  
       "id": "12e6f869-6675-4488-bd47-ccd298f55b3f",
       "amount": "1.00",
       "currency": "EUR",
       "type": "refund",
       "created": "2015-01-17T09:15:27Z",
       "live": false,
       "parent_id": "90ebe1a8-ebaf-48c5-b654-19c8e6ae5368",
       "status": "approved",
       "description": "some description"
   }
]

To retrieve all refunds for a specific payment you have to send a GET request providing a payment id.

HTTP Request

GET https://api.cardinity.com/v1/payments/{PAYMENT_ID}/refunds

Response

Returns a list of refund objects. Response code: 200.

Settlements

To settle a payment you have to create a new settlement object. You can retrieve individual settlement for a specific payment. Settlements are identified by a UUID.

Settlement Object

Example: Approved Settlement

{  
   "id": "25e6f869-6675-4488-bd47-ccd298f74b3f",
   "amount": "0.50",
   "currency": "EUR",
   "type": "settlement",
   "created": "2015-01-16T09:05:27Z",
   "live": true,
   "parent_id": "f02862aa-5dcc-4637-9ddf-b9140c2b4b06",
   "status": "approved"
}

Attributes

Name Type Description
id UUID ID of the settlement.
Value assigned by Cardinity.
amount decimal Amount settled shown in #0.00 format.
currency string Three-letter ISO currency code representing the currency in which the settlement was made. Supported currencies: EUR, GBP, USD.
Value assigned by Cardinity.
type string Can only be: settlement.
Value assigned by Cardinity.
created datetime Settlement creation time as defined in RFC 3339 Section 5.6. UTC timezone.
Value assigned by Cardinity.
live boolean Indicates whether settlement was made in live or testing mode.
Value assigned by Cardinity.
parent_id UUID ID of the settled payment.
Value assigned by Cardinity.
status string Settlement status. Can be one of the following: approved or declined.
Value assigned by Cardinity.
error string Error message. Returned only if status is declined. Provides human readable information why a settlement failed.
Value assigned by Cardinity.
order_id string Optional. Order ID provided by a merchant in initial payment. Must be between 2 and 50 characters [A-Za-z0-9'.-].
Value assigned by Cardinity.
description string Optional. Settlement description provided by a merchant. Maximum length 255 characters.

Create new settlement

Example Request

<?php

use Cardinity\Client;
use Cardinity\Method\Settlement;

$client = Client::create([
    'consumerKey' => 'YOUR_CONSUMER_KEY',
    'consumerSecret' => 'YOUR_CONSUMER_SECRET',
]);

$method = new Settlement\Create(
    $payment->getId(),
    10.00,
    'my description'
);
/** @type Cardinity\Method\Settlement\Settlement */
$result = $client->call($method);

?>
CardinityClient client = new CardinityClient(consumerKey, consumerSecret);

Settlement settlement = new Settlement(new BigDecimal(10));
Result<Settlement> result = client.createSettlement(paymentId, settlement);

/** Request was valid and settlement was approved. */
if (result.isValid() && result.getItem().getStatus() == Settlement.Status.APPROVED) {
    settlement = result.getItem();
    // proceed with successful settlement flow
}

/** Request was valid but settlement was declined. */
else if (result.isValid()) {
     String declineReason = result.getItem().getError();
     // proceed with declined settlement flow
}

/** Request was invalid. */
else {
    CardinityError error = result.getCardinityError();
    // handle error
}
curl https://api.cardinity.com/v1/payments/90ebe1a8-ebaf-48c5-b654-19c8e6ae5368/settlements \
-H "Content-Type: application/json" \
-H "Authorization: OAuth <OAuth Details>" \
-d '{
    "amount": "10.00",
    "description": "some description"
}'

# Response JSON
{
   "id": "25e6f869-6675-4488-bd47-ccd298f74b3f",
   "amount": "10.00",
   "currency": "EUR",
   "type": "settlement",
   "created": "2015-01-16T09:05:27Z",
   "live": false,
   "parent_id": "90ebe1a8-ebaf-48c5-b654-19c8e6ae5368",
   "status": "approved",
   "description": "some description"
}

To settle authorized payment you have to create a new settlement object providing Payment Id and amount to be settled. Only one settlement for a payment is allowed. You can not settle larger amount than it was authorized.

HTTP Request

POST https://api.cardinity.com/v1/payments/{PAYMENT_ID}/settlements

Request Attributes

Name Type Required Description
amount decimal Yes Amount to be settled. Only positive values are allowed. Format: #0.00, two decimal places precision is required.
description string No Settlement description provided by a merchant. Maximum length 255 characters.

Response

Returns a settlement object if:

Returns an error object otherwise. Response codes: 400, 401, 405, 500, 503.

If a Settlement was declined (status: declined) Settlement object contains error attribute explaining why this happened.

Get existing settlement

Request Example

<?php

use Cardinity\Client;
use Cardinity\Method\Settlement;

$client = Client::create([
    'consumerKey' => 'YOUR_CONSUMER_KEY',
    'consumerSecret' => 'YOUR_CONSUMER_SECRET',
]);

$method = new Settlement\Get(
    $payment->getId(),
    $settlement->getId()
);
/** @type Cardinity\Method\Settlement\Settlement */
$settlement = $client->call($method);

?>
CardinityClient client = new CardinityClient(consumerKey, consumerSecret);

Result<Settlement> result = client.getSettlement(paymentId, settlementId);

if (result.isValid()) {
    Settlement settlement = result.getItem();
}
else {
    CardinityError error = result.getCardinityError();
}  
curl https://api.cardinity.com/v1/payments/cb5e1c95-7685-4499-a2b1-ae0f28297b92/settlements/25e6f869-6675-4488-bd47-ccd298f74b3f \
  -H "Content-Type: application/json" \
  -H "Authorization: OAuth <OAuth Details>"

To retrieve a specific settlement you have to send GET request providing an ID of a payment and ID of a settlement.

HTTP Request

GET https://api.cardinity.com/v1/payments/{PAYMENT_ID}/settlements/{SETTLEMENT_ID}

Response

Returns a settlement object if settlement was found. Response code: 200.

Returns an error object if settlement was not found. Response code: 404.

Get all settlements

Request Example

<?php

use Cardinity\Client;
use Cardinity\Method\Settlement;

$client = Client::create([
    'consumerKey' => 'YOUR_CONSUMER_KEY',
    'consumerSecret' => 'YOUR_CONSUMER_SECRET',
]);

$method = new Settlement\GetAll(
    $payment->getId()
);
$result = $client->call($method);
/** @type Cardinity\Method\Settlement\Settlement */
$settlement = $result[0];

?>
CardinityClient client = new CardinityClient(consumerKey, consumerSecret);

Result<List<Settlement>> result = client.getSettlements(paymentId);

if (result.isValid()) {
    List<Settlement> settlements = result.getItem();
}
else {
    CardinityError error = result.getCardinityError();
}
curl https://api.cardinity.com/v1/settlements/90ebe1a8-ebaf-48c5-b654-19c8e6ae5368/settlements \
  -H "Content-Type: application/json" \
  -H "Authorization: OAuth <OAuth Details>"

# Response JSON
[  
   {
       "id": "25e6f869-6675-4488-bd47-ccd298f74b3f",
       "amount": "5.00",
       "currency": "EUR",
       "type": "settlement",
       "created": "2015-01-16T09:05:27Z",
       "live": false,
       "parent_id": "90ebe1a8-ebaf-48c5-b654-19c8e6ae5368",
       "status": "approved",
       "description": "some description"
   }
]

To retrieve a settlement for a specific payment you have to send GET request providing a payment id.

HTTP Request

GET https://api.cardinity.com/v1/payments/{PAYMENT_ID}/settlements

Response

Returns a list of settlement objects. Response code: 200.

Voids

To void an authorized payment you have to create a new void object. You can retrieve individual void for a specific payment. Voids are identified by a UUID.

Void Object

Example: Approved Void

{  
   "id": "25e6f869-6675-4488-bd47-ccd298f74b3f",
   "type": "void",
   "created": "2015-01-16T09:05:27Z",
   "live": true,
   "parent_id": "f02862aa-5dcc-4637-9ddf-b9140c2b4b06",
   "status": "approved"
}

Attributes

Name Type Description
id UUID ID of the void.
Value assigned by Cardinity.
type string Can only be: void.
Value assigned by Cardinity.
created datetime Void creation time as defined in RFC 3339 Section 5.6. UTC timezone.
Value assigned by Cardinity.
live boolean Indicates whether void was made in live or testing mode.
Value assigned by Cardinity.
parent_id UUID ID of the voided payment.
Value assigned by Cardinity.
status string Void status. Can be one of the following: approved or declined.
Value assigned by Cardinity.
error string Error message. Returned only if status is declined. Provides human readable information why a void failed.
Value assigned by Cardinity.
order_id string Optional. Order ID provided by a merchant in initial payment. Must be between 2 and 50 characters [A-Za-z0-9'.-].
Value assigned by Cardinity.
description string Optional. Void description provided by a merchant. Maximum length: 255 characters.

Create new void

Example Request

<?php

use Cardinity\Client;
use Cardinity\Method\VoidPayment;

$client = Client::create([
    'consumerKey' => 'YOUR_CONSUMER_KEY',
    'consumerSecret' => 'YOUR_CONSUMER_SECRET',
]);

$method = new VoidPayment\Create(
    $payment->getId(),
    'my description'
);
/** @type Cardinity\Method\VoidPayment\VoidPayment */
$result = $client->call($method);

?>
CardinityClient client = new CardinityClient(consumerKey, consumerSecret);

Result<Void> result = client.createVoid(paymentId, new Void());

/** Request was valid and void was approved. */
if (result.isValid() && result.getItem().getStatus() == Void.Status.APPROVED) {
    Void voidPayment = result.getItem();
    // proceed with successful void flow
}

/** Request was valid but void was declined. */
else if (result.isValid()) {
     String declineReason = result.getItem().getError();
     // proceed with declined void flow
}

/** Request was invalid. */
else {
    CardinityError error = result.getCardinityError();
    // handle error
}
curl https://api.cardinity.com/v1/payments/90ebe1a8-ebaf-48c5-b654-19c8e6ae5368/voids \
-H "Content-Type: application/json" \
-H "Authorization: OAuth <OAuth Details>" \
-d '{
    "description": "some description"
}'

# Response JSON
{
   "id": "25e6f869-6675-4488-bd47-ccd298f74b3f",
   "type": "void",
   "created": "2015-01-16T09:05:27Z",
   "live": false,
   "parent_id": "90ebe1a8-ebaf-48c5-b654-19c8e6ae5368",
   "status": "approved",
   "description": "some description"
}

To void an authorized payment you have to create a new void object providing Payment Id.

HTTP Request

POST https://api.cardinity.com/v1/payments/{PAYMENT_ID}/voids

Request Attributes

Name Type Required Description
description string No Void description provided by a merchant. Maximum length: 255 characters.

Response

Returns a void object if:

Returns an error object otherwise. Response codes: 400, 401, 405, 500, 503.

If a void was declined (status: declined) Void object contains error attribute explaining why this happened.

Get existing void

Request Example

<?php

use Cardinity\Client;
use Cardinity\Method\VoidPayment;

$client = Client::create([
    'consumerKey' => 'YOUR_CONSUMER_KEY',
    'consumerSecret' => 'YOUR_CONSUMER_SECRET',
]);

$method = new VoidPayment\Get(
    $payment->getId(),
    $void->getId()
);
/** @type Cardinity\Method\VoidPayment\VoidPayment */
$void = $client->call($method);

?>
CardinityClient client = new CardinityClient(consumerKey, consumerSecret);

Result<Void> result = client.getVoid(paymentId, voidId);

if (result.isValid()) {
    Void voidPayment = result.getItem();
}
else {
    CardinityError error = result.getCardinityError();
} 
curl https://api.cardinity.com/v1/payments/cb5e1c95-7685-4499-a2b1-ae0f28297b92/voids/25e6f869-6675-4488-bd47-ccd298f74b3f \
  -H "Content-Type: application/json" \
  -H "Authorization: OAuth <OAuth Details>"

To retrieve a specific void you have to send GET request providing an ID of a payment and ID of a void.

HTTP Request

GET https://api.cardinity.com/v1/payments/{PAYMENT_ID}/voids/{VOID_ID}

Response

Returns a void object if void was found. Response code: 200.

Returns an error object if void was not found. Response code: 404.

Get all voids

Request Example

<?php

use Cardinity\Client;
use Cardinity\Method\VoidPayment;

$client = Client::create([
    'consumerKey' => 'YOUR_CONSUMER_KEY',
    'consumerSecret' => 'YOUR_CONSUMER_SECRET',
]);

$method = new VoidPayment\GetAll(
    $payment->getId()
);
$result = $client->call($method);
/** @type Cardinity\Method\VoidPayment\VoidPayment */
$void = $result[0];

?>
CardinityClient client = new CardinityClient(consumerKey, consumerSecret);

Result<List<Void>> result = client.getVoids(paymentId);

if (result.isValid()) {
    List<Void> voids = result.getItem();
}
else {
    CardinityError error = result.getCardinityError();
}
curl https://api.cardinity.com/v1/payments/90ebe1a8-ebaf-48c5-b654-19c8e6ae5368/voids \
  -H "Content-Type: application/json" \
  -H "Authorization: OAuth <OAuth Details>"

# Response JSON
[  
   {
       "id": "25e6f869-6675-4488-bd47-ccd298f74b3f",
       "type": "void",
       "created": "2015-01-16T09:05:27Z",
       "live": false,
       "parent_id": "90ebe1a8-ebaf-48c5-b654-19c8e6ae5368",
       "status": "approved",
       "description": "some description"
   }
]

To retrieve a void for a specific payment you have to send GET request providing payment id.

HTTP Request

GET https://api.cardinity.com/v1/payments/{PAYMENT_ID}/voids

Response

Returns a list of void objects. Response code: 200.

Response / Error Codes

In case of an error Cardinity API returns JSON structured like this:

{
    "type": "https://developers.cardinity.com/api/v1/#400",
    "title": "Validation Failed",
    "status": 400,
    "detail": "The content you've send contains 2 validation errors.",
    "errors": [
        {
            "field": "currency",
            "rejected": "EGR",
            "message": "invalid or unsupported currency"
        },
        {
            "field": "payment_instrument.exp_month",
            "rejected": 13,
            "message": "must be between 1 and 12"
        }
    ]
}

Cardinity uses RFC 7231 HTTP response codes to indicate success or failure of an API request.

Codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing, a credit card was declined, etc.), and codes in the 5xx range indicate an error on Cardinity's end.

In case of an error, specific object is returned which contains detailed information about the error which occurred.

Error Object Attributes

Attribute Description
type URL to error's documentation page
title Title of an error
status HTTP response code
detail Human readable information about the error
errors Optional. In case of validation errors all the fields with incorrect information are returned.

Response Codes

Code Meaning
200 OK -- Indicates successful retrieval of a resource. Used only in response for GET method requests.
201 Created -- Successful creation of a resource (e.g. successful payment, refund, etc). Used in response for POST and PATCH method requests.
202 Accepted -- Payment was accepted but is in a pending state. You must provide additional information to complete this payment.

Error Codes

Base exception class for Cardinity client: Cardinity\Exception\Runtime
Catching this exception ensures that you handle all cardinity failure use cases.

Base class for API error response exceptions: Cardinity\Exception\Request

Methods:
* getErrors() returns list of errors occured
* getErrorsAsString() returns list of errors occured in string form
* getResult() returns object, the instance of ResultObjectInterface.

All classes

Class: Cardinity\Exception\ValidationFailed
HTTP status: 400

Class: Cardinity\Exception\Unauthorized
HTTP status: 401

Class: Cardinity\Exception\Declined
HTTP status: 402

Class: Cardinity\Exception\Forbidden
HTTP status: 403

Class: Cardinity\Exception\NotFound
HTTP status: 404

Class: Cardinity\Exception\MethodNotAllowed
HTTP status: 405

Class: Cardinity\Exception\NotAcceptable
HTTP status: 406

Class: Cardinity\Exception\InternalServerError
HTTP status: 500

Class: Cardinity\Exception\ServiceUnavailable
HTTP status: 503


Cardinity client exceptions

Request timed out: Cardinity\Exception\RequestTimeout

Before-request data validation failed: Cardinity\Exception\InvalidAttributeValue
Methods:
* getViolations() returns list of validation violations

Response mapping to result object failure: Cardinity\Exception\ResultObjectInterfacePropertyNotFound

Unexpected error: Cardinity\Exception\UnexpectedError
Call of CardinityClient methods may result in unchecked exception being thrown. 

Base exception class is CardinityException

There can be two types of exceptions thrown:

* ValidationException - validation of data passed to method has failed.
* CardinityClientException - network errors, internal client errors, etc.
Code Meaning
400 Bad Request -- Your request contains field or business logic validation errors or provided JSON is malformed.
401 Unauthorized -- Your authorization information was missing or wrong.
402 Request Failed -- Your request was valid but it was declined.
403 Forbidden -- You do not have access to this resource.
404 Not Found -- The specified resource could not be found.
405 Method Not Allowed -- You tried to access a resource using an invalid HTTP method.
406 Not Acceptable -- Wrong Accept headers sent in the request.
415 Unsupported Media Type -- Wrong Content-Type headers sent in the request.
500 Internal Server Error -- We had a problem on our end. Try again later.
503 Service Unavailable -- We're temporarily off-line for maintenance. Please try again later.

Hosted Payment Page

Hosted Payment Page

All requests and responses must be signed and verified using HMAC-SHA256

Checkout HTTP Request

Example Request

curl https://checkout.cardinity.com \
-H "Content-Type: application/json" \
-d '{
    "amount": "1.00",
    "cancel_url": "https://webiste.url/cancel",
    "country": "LT",
    "currency": "EUR",
    "description": "some description",
    "order_id": "12345678",
    "project_id": "test_pr_123",
    "return_url": "https://webiste.url/return",
    "signature": {your_signature}
}'
<?php

$attributes = [
    "amount" => "10.00",
    "currency" => "EUR",
    "country" => "LT",
    "order_id" => "99999",
    "project_id" => $projectId,
    "return_url" => $returnUrl,
];
ksort($attributes);

$message = '';
foreach($attributes as $key => $value) {
    $message .= $key.$value;
}

$signature = hash_hmac('sha256', $message, $projectSecret);

?>
try {
    Map<String, String> attributes = new HashMap<>();

    attributes.put("amount", "10.00");
    attributes.put("currency", "EUR");
    attributes.put("country", "LT");
    attributes.put("order_id", "99999");
    attributes.put("project_id", projectId);
    attributes.put("return_url", returnUrl);

    String message = attributes.entrySet().stream()
        .sorted(Map.Entry.comparingByKey())
        .map(e -> e.getKey() + e.getValue())
        .collect(Collectors.joining(""));

    Mac hasher = Mac.getInstance("HmacSHA256");
    hasher.init(new SecretKeySpec(projectSecret.getBytes(), "HmacSHA256"));

    byte[] hash = hasher.doFinal(message.getBytes());

    String signature = DatatypeConverter.printHexBinary(hash).toLowerCase();
} catch (NoSuchAlgorithmException e) {
} catch (InvalidKeyException e) {
}

Example Request Form

<html>
   <head>
      <title>Request Example | Hosted Payment Page</title>
   </head>
   <body onload="document.forms['checkout'].submit()">
      <form name="checkout" method="POST" action="https://checkout.cardinity.com">
          <button type=submit>Click Here</button>
          <input type="hidden" name="amount" value="{amount}" />
          <input type="hidden" name="cancel_url" value="{cancel_url}" />
          <input type="hidden" name="country" value="{country}" />
          <input type="hidden" name="currency" value="{currency}" />
          <input type="hidden" name="description" value="{description}" />
          <input type="hidden" name="order_id" value="{order_id}" />
          <input type="hidden" name="project_id" value="{project_id}" />
          <input type="hidden" name="return_url" value="{return_url}" />
          <input type="hidden" name="signature" value="{signature}" />
      </form>
   </body>
</html>

POST https://checkout.cardinity.com

Request Attributes

Name Type Required Description
amount decimal Yes Amount to charge. Only positive values are allowed. Format: #0.00, two decimal places precision is required.
cancel_url string No URL to which customer is redirected upon canceling payment flow. Must be valid url address up to 500 characters.
country string Yes Country of a customer obtained via geolocation services or entered manually. ISO 3166-1 alpha-2 country code.
currency string Yes Three-letter ISO currency code representing the currency of the amount. Supported currencies: EUR, GBP, USD.
description string No Payment description provided by a merchant. Maximum length 255 characters.
order_id string Yes Order ID provided by a merchant. Must be between 2 and 50 characters [A-Za-z0-9'.-].
project_id string Yes Project ID provided by Cardinity.
return_url string Yes URL to which customer is redirected upon completing payment flow. Must be valid url address up to 500 characters.
signature string Yes String made up of request parameters joined in a single string in ascending order, according to the key which is then encrypted via HMAC-SHA256 using your Project Secret.

Checkout HTTP Response

Example Response

<?php

$message = '';
ksort($_POST);

foreach($_POST as $key => $value) {
    if ($key == 'signature') continue;
    $message .= $key.$value;
}

$signature = hash_hmac('sha256', $message, $projectSecret);

if ($signature == $_POST['signature']) {
    // Response valid
} else {
    // Response invalid or changed
}

?>

Response Attributes

Name Type Required Description
amount decimal Yes Amount shown in #0.00 format.
country string Yes Country of a customer provided by a merchant. ISO 3166-1 alpha-2 country code.
created datetime Yes Payment creation time as defined in RFC 3339 Section 5.6. UTC timezone.
currency string Yes Three-letter ISO currency code representing the currency in which the charge was made.
description string No Payment description provided by a merchant.
error string No Error message. Returned only if status is declined.
id UUID Yes ID of the payment.
live boolean Yes Indicates whether a payment was made in live or testing mode.
order_id string Yes Order ID provided by a merchant.
payment_method string Yes Can be card only.
project_id string Yes Project ID provided by a merchant.
signature string Yes String made up of response parameters joined in a single string in ascending order, according to the key which is then encrypted via HMAC-SHA256 using your Project Secret.
status string Yes Payment status.
type string Yes Payment type.