API Documentation

This documentation is written and tested for the Payment Gateway API and the Portal API.

Changelog

The following table describes the changes made to this document. Each change results in a new version number (SemVer 2.0.0). The date of each change is in yyyy-MM-dd format.

Date Version PHP Library Version Change
2019-04-16 1.0.0 1.0.0 Initial version
2019-04-16 1.1.0 Not updated Added array of payment methods in terminal model
2019-04-18 1.2.0 Not updated Hosted Page changed & Images added
2019-04-23 1.2.1 Not updated Added more samples
2019-05-02 1.2.2 1.0.1 Moved endpoints to staging environment
2019-05-02 1.3.0 Not updated Login procedure changed to identity server
2019-05-08 1.4.0 Not updated Added documentation on how to integrate GoogleAnalytics
2019-05-21 1.4.1 Not updated Post request for creating terminals with generated terminal id
2019-06-03 1.4.2 Not updated Changes in retrieving traces and terminals
2019-06-04 1.4.3 Not updated Possibility to retrieve daily statistics
2019-06-05 1.5.0 Not updated Expanded PayPal config object
2019-06-18 1.6.0 1.0.2 Options introduced when creating payment job
2019-06-21 1.7.0 Not updated Added account updater
2019-06-28 1.8.0 Not updated Added customer support.
2019-07-09 1.9.0 Not updated Added a list of tokenized creditcards to the response of the supported payment list
2019-07-10 1.10.0 1.0.3 Added support for creditcard tokenization
2019-07-12 1.11.0 1.0.4 Updated models
2019-07-25 1.12.0 Not updated PortalApi model of UserInfo has changed
2019-07-30 1.13.0 Not updated PortalApi altered api/portal/terminals/{BusinessId}/{MerchantId}
2019-07-31 1.14.0 Not updated Added export customers
2019-08-06 1.15.0 Not updated Made currency in create payment job request required.
2019-08-07 1.16.0 Not updated Changed portal configurations endpoint based on domain+userid+key
2019-08-09 1.17.0 Not updated Retrieve terminals only with business id and merchant id
2019-18-16 1.18.0 Not updated Create and retrieve users
2019-08-20 1.19.0 Not updated Endpoint changed for create terminal and retrieve terminals
2019-08-21 1.19.1 Not updated Create, update and retrieve user settings
2019-08-21 1.19.2 Not updated Update and delete users
2019-08-21 1.20.0 Not updated Possibility to send bug reports
2019-08-22 1.21.0 Not updated Endpoints refactored to '/businesses/{BusinessId}/merchants/{MerchantId}/terminals'
2019-08-22 1.22.0 Not updated Added abuse settings to payment method configurations
2019-08-23 1.23.0 Not updated Added abuse report and abuse trigger models, and included those in the payment model
2019-08-23 1.23.1 Not updated Added request and response examples for abuse changes
2019-08-26 1.24.0 Not updated Removed logo URL property from PaymentMethodInfo model, Issuer model and corresponding request/response examples
2019-08-26 1.25.0 Not updated Access model changed. Credentials object added.
2019-09-02 1.25.5 1.0.5 Explain tokenization, Abuse reporting introduced and set correct integration path UK
2019-09-04 1.26.0 Not updated Updated hosted payment page configuration models.
2019-09-06 1.27.0 Not updated Updated hosted payment page configuration models.
2019-09-10 1.27.1 1.0.6 Updated payment with payment flags.
2019-09-10 1.27.2 Not updated Updated payment examples with altered abuse report code for CyberSource total.
2019-09-11 1.27.3 1.0.7 Moved OriginatingIpAddress to payment attributes.
2019-09-17 1.27.4 Not updated Corrected typo, removed showdeleted query parameter when retrieving users, documented delete user settings, fixed some responsecode descriptions
2019-09-25 1.28.0 Not updated Protected image write requests (post and delete) with OAuth: moved the write requests to a new path.
2019-09-26 1.29.0 Not updated Added logos to response of supported payment methods request.
2019-10-03 1.30.0 Not updated Added enumeration endpoints and models for these endpoints.
2019-10-03 1.31.0 Not updated Added search term query parameter in retrieve terminals endpoints.

Base Response Object

All API calls that have a httpcode < 500 and are not 204, will return a BaseResponseObject in the message body. (All properties that don't have a value not serialized)

Property Type Remark
data object If data is retrieved it is here
errorReport string If omitted, type 'Payment' is used
errorReport.language string Locale of translatedMessage(s)
errorReport.isFatalError boolean When true call failed. when false succeeded with limitations
errorReport.errors array[Entry] Error details
errorReport.warnings array[Entry] Warning details
links Links The predefined list of links
links.data Link Link that can retrieve the latest modification
links.action Link Link for a succeeding action, for example a paymentlink
links.documentation Link Link to corresponding documentation
{
	"data": "some data object",
    "errorReport": {
        "language": "nl_NL",
        "isFatalError": "true",
        "errors": [
            {
                "code": "ErrorCode",
                "message": "Error message default",
                "translatedMessage": "Foutmelding standaard",
                "parameters": [
                    "default"
                ]
            }
        ],
        "warnings": [
            {
                "code": "WarningCode_1",
                "message": "Warning message default",
                "translatedMessage": "Waarschuwingsbericht standaard",
                "parameters": [
                    "default"
                ]
            }
        ]
    },
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Payment Gateway API Overview

The payment gateway api provides an api for creating new payment jobs, refunds, invoices, and other payment related operations. This service handles extensive validation and conversion for each request, as well as providing a security layer by doing authentication and authorization checks.

Setting it all up

You can install the needed PHP library using the composer command:

composer require cashflows/php_payment-gateway-api

If you want to have a look at the PHP source library it is located at github.

For other languages you can create the required json commands studying the model section.

Signing API calls

To assure message consistency and making it hard to execute a man in the middle attack all messages are signed with a SHA512 hash. This hash is calculated by appending the body data to the API password (password comes first). The calculated byte buffer is converted to a hex-string and send in the header with "Hash: xxxxxx". If the message body is empty just hash the password.

The gateway has the ability to have 2 passwords available at one time. When altering a password you first create a new second password. If all the systems have migrated to the new password than you can remove the first password. This way you can alter a password without having migration downtime.

PHP signing code sample

<?php

echo 'Start hash calculation';

$bodyData = '{ "object": "data" }';
$password = '7C4551BC-07FB-4D31-8E1A-7B195156DD14';

echo 'Hash is ' . hashCreate::Calculate($password,$bodyData);

// Output of Hash is 2B9D940370A8713578D0EA2EAF56786C6FD09EDA50C3DB7118EF0BDAC7A245DB176B58A2C452D9783CE7BA7566A2AD2B704A1307856FA461BDE7048D6051DF35


class hashCreate
{
	static function Calculate($password, $bodyData)
	{
		$computedHash = hash('sha512', $password . $bodyData, true);
		return strtoupper(bin2hex($computedHash));
	}
}

TerminalId header

If you have been setup to use the gateway you will receive a TerminalId. The terminalId identifies your application to the gateway with it's defined setup properies. Beside the hash you will have to supply the terminalId in the html header of each call to the gateway. The headerformat should look like: "TerminalId: xxxxx".

API Endpoints

The gateway software is designed to be able to run on a configurable domain name. likely change overtime. Also different domains for staging, sandbox and production will become available in time.

Payment Gateway Api endpoints:

Country Endpoint Endpoint type
UK https://gateway-int.cashflows.com Integration environment (Sandbox)
UK https://gateway.cashflows.com Production environment (Live)
NL https://sandbox.paycheckout.com Integration environment (Sandbox )
NL https://secure.paycheckout.com Production environment (Live)

You can verify operation of the gateway by performing a GET operation on the endpoint:

Possible success response codes:

Code Description
200 Service is healthy
* Any other code indicates service is not healthy
GET
[domain]/api/gateway

Webhooks

It is important for a smooth and safe operation of a paymentapplication to implement webhooks. A webhook is an api endpoint you create on your server implementation. This endpoint will be called from the gateway software on statuschanges of your paymentjob. This way you avoid having to poll for a paymentstatus changes, instead you will be notified of paymentjobs from which the status has changed.

NOTE Never assume the payment status queryparameter of a paymentjob is correct as this return value can be easily manipulated. This status is just a way to inform the user about his payment status, always use webhooks or if you do not have the ability to offer a public endpoint, query the paymentjob by yourself to get the actual paymentstatus.

Expected behaviour of such an endpoint. The gateway will perform a POST operation at the specified webhook url when the status of a paymentjob changes. For example from "Pending" into "Paid". The body consist of notifyType, PaymentjobReference and PaymentReference.

The paymentapplication can retrieve the paymentjobReference and check it's status. Typically an internal delivery process is started for the order involved if the status get's "Paid" or "Reserved". The gateway expects a json ack response confirming the paymentjobreference and paymentreference in the following format

When the gateway receives the confirmed paymentjobReference and paymentReference the webhook procedure will end until another status change occurs.

If the response does not contain the expected ack json with a httpstatus 200 OK, or there is no response at all the webhook call will get repeated at different intervals. The intervals between attempts are according the following table

Attempt Interval
0 - 12 10 sec
13 - 30 1 min
31 - 37 5 min
38 - 50 10 min
51 - 62 30 min
63 - 77 1 hour
78 - 89 4 hours
90 - 101 8 hours

When notification fails after the 101st attempt (after a total of 1 week of attempts) an email is sent to the technical email address, if available, to inform the webhook was not handled correctly and further attempts are cancelled.

Webhook post request body

{
  "notifyType": "PaymentStatusChange",
  "paymentJobReference": "190421021508522012",
  "paymentReference": "190421121651132420"
}

Webhook post response body

{
  "paymentJobReference": "190421021508522012",
  "paymentReference": "190421121651132420"
}

GoogleAnalytics integration

In order to use GoogleAnalytics you have to perform 3 steps:

  1. Fetch the content of the '_ga' cookie and pass that string as the PaymentjobParameter.GoogleAnalyticsClientId parameter when creating a paymentjob. As an example this should look like 'GA1.2.501991274.1543589322'.
  2. Configure your Google Analytics Tracking-ID (example: US-12345678-1) in the gateway using the portal.
  3. Configure the gateway endpoint (example: paycheckout.com) in the Referral Exclusion list in google analytics. This is necessary to avoid creating a new sessioncookie when going to the gateway url. For more information visit https://support.google.com/analytics/answer/1034342?hl=en#Next.

You can verify operation by completing the paymentjob by fully paying it and than search for the call the gateway performs to google analytics in the trace. The postcommand value 'tid' should show the configured Google Analytics Tracking-ID and the 'cid' value should show the supplied '_ga' cookie value. If these are correct you have succesfully integrated.

Scenarios

In the following section we describe scenario's and there corresponding API calls

Populating paymentmethods in the checkoutpage

When you are performing a shop integration there will be a section in the checkout page where the paymentmethods should be presented to the buyer.

We provide an api call Retrieve suppported payment methods to populate this section.

This call will provide all the available paymentmethods for this checkout including payment logo's surcharges etc. By implementing the result data of this call correctly will make the checkout page ready for all future paymentmethods, avoiding having to do development eachtime a new paymentmethod becomes available.

Creating a basic payment(job)

In order to collect money a paymentjob should be created. We assume you have setup paymentmethods for the terminal and a set of redirect urls for a paid, failed or cancelled payment. As a minimum you specify the amount to collect, currency and localisation for the paymentjob. As a response you will receive a redirect link (action link) where you should redirect the browser of the buyer too in order to complete the payment.

Webhook We strongly advise to supply a webhook url pointing to an api endpoint on your server side. This way you will get notified if the buyer has succesfully made a payment without you having to poll for the paymentjob status. See webhooks.

NOTE This minimum requirement to start a paymentjob is in many cases not sufficient. We advise to at least supply the ordernumber and the billingidentity.email when creating a paymentjob. Generally speaking supply all that you know. Without this information payment lookup and reconsiliation of payments will become a hard job if at all possible.

Creating a basis payment job (PHP)

<?php

echo "Starting\n";

require __DIR__ . '/vendor/autoload.php';

// Create an executor instance
$execute = new \PaymentGateway\Executor("12345","DE6DA27F-ACFC-463B-91F7-F852FEAC257C","https://gatewayendpoint.example.com");

// Prepare PostRequest
$postRequest = new \PaymentGateway\Api\PaymentJobs\PostRequest();
$postRequest->setLocale(\PaymentGateway\Model\Locale::en_GB);
$postRequest->setAmountToCollect(121);
$postRequest->setCurrency(\PaymentGateway\Model\Currency::GBP);


// Execute the call
$execute->callEndPoint("/api/gateway/payment-jobs","POST",$postRequest);

// Analyze result
if ($execute->isSuccess())
{
    $result = new \PaymentGateway\Api\PaymentJobs\PostResponse();
    $execute->getMappedResponse($result);

	echo "redirectlink->" . $result->getLinks()->getAction()->getUrl() . "<br/>";
}
else
{
    if ($execute->isCurlError())
    {
        var_dump($execute->getCurlError());
        return;
    }
    $result = $execute->getHttpCode() . "[" . $execute->getResponseBody() . "]";
    var_dump($result);
}

echo "<br/>Complete";

Direct acquiring

If you are PCI-DSS compliant you can use the gateway to perform creditcard acquiring. By direct acquiring we mean that you gather the creditcard information on your servers and create a paymentjob whilst supplying the creditcard information at the start of a payment. If a 3dSecure call is needed the redirectlink will point you to the 3d secure supplier. If the payment is directly approved you can still use the redirectlink but in that case it will point to the defined success url if the creditcard is authorized.

You add the creditcard information to the paymentjob by populating the creditcard parameters. In the case of AMEX where adress and email information is required supply them thru the order billing identity and billing address.

Fields to supply for AMEX
order.billingAddress.firstName
order.billingAddress.middleName
order.billingAddress.lastName
order.billingAddress.addresLine1
order.billingAddress.addresLine2
order.billingAddress.zipCode
order.billingAddress.city
order.billingAddress.stateProvince
order.billingAddress.countryIso3166Alpha2
order.billingAddress.phoneNumber1
order.billingIdentity.emailAddress

Direct acquiring sample (PHP)

<?php

echo "Starting\n";

require __DIR__ . '/vendor/autoload.php';

// Create an executor instance
$execute = new \PaymentGateway\Executor("12345","DE6DA27F-ACFC-463B-91F7-F852FEAC257C","https://gatewayendpoint.example.com");

// Prepare PostRequest with Mastercard direct acquiring
$postRequest = new \PaymentGateway\Api\PaymentJobs\PostRequest();
$postRequest->setLocale(\PaymentGateway\Model\Locale::en_GB);
$postRequest->setAmountToCollect(121.5);
$postRequest->setCurrency(\PaymentGateway\Model\Currency::GBP);

// Select creditcard as the only paymentmethod
$postRequest->addPaymentMethod(\PaymentGateway\Model\PaymentMethod::Creditcard);

// Supply creditcard information
$postRequest->addParameter(\PaymentGateway\Api\PaymentJobs\PaymentJobParameter::cardNumber,"4000000000000002");
$postRequest->addParameter(\PaymentGateway\Api\PaymentJobs\PaymentJobParameter::cardExpiryMonth,"2");
$postRequest->addParameter(\PaymentGateway\Api\PaymentJobs\PaymentJobParameter::cardExpiryYear,"21");
$postRequest->addParameter(\PaymentGateway\Api\Gateway\PaymentJobs\PaymentJobParameter::cardHolder,"{ cardHolderName: \"Name on card\" }");
$postRequest->addParameter(\PaymentGateway\Api\PaymentJobs\PaymentJobParameter::cardCvc,"123");


// Execute the call
$execute->callEndPoint("/api/gateway/payment-jobs","POST",$postRequest);

// Analyze result
if ($execute->isSuccess())
{
    //echo "<br>json->" . ($execute->getResponseBody()) . "<br>";

    $result = new \PaymentGateway\Api\PaymentJobs\PostResponse();
    $execute->getMappedResponse($result);

	echo "redirectlink->" . $result->getLinks()->getAction()->getUrl() . "<br/>";

    //var_dump($result);


}
else
{
    if ($execute->isCurlError())
    {
        var_dump($execute->getCurlError());
        return;
    }
    $result = $execute->getHttpCode() . "[" . $execute->getResponseBody() . "]";
    var_dump($result);
}

echo "<br/>Complete";

Reservations and captures

If your business requires you to perform (creditcard) reservations first and capture the reservations later the gateway can support this scenario. Currently partical captures for creditcards are not possible, they are possible for PayPal.

If a paymentjob first reserves an amount and later captures the amount is a setting for the terminal and corresponding payment method. The default is "autoCapture" true. So if you do not set autoCapture to false authorized amounts are always immediatly captured.

Scenario's where you would want to set autoCapture to false are in cases where you can not deliver the goods immediatly. In this scenario you just want to capture the amount at the time you are ready to deliver the goods and in the meantime want to be sure that when the goods arrive you will receive the reserved funds.

So if you have set "autoCapture" to false you must "manually" capture the amount via a seperate api call if the paymentjob status has reached the "Reserved" status. As soon as the paymentjob reaches the status "Reserved" you can capture the reserved amount. If you do not specify "AmountToCapture" the full reserved amount will be captured. In case of creditcard capturing the full amount is the only option now.

The cookbook to create a reservation/capture scenario is to start paymentjobs as normal, having the terminal setting for the paymentmethod set to "autoCapture" false value. And then call Capture as soon as the paymentjob status turns into "Reserved" and you are ready to deliver.

Refunding

When you want to refund an amount because for example goods are returned you can call the Refunds method to refund an amount. In order to do so you need the paymentjobreference and paymentreference of the payment within the paymentjob that was used to pay an amount. You can not refund more in one call than the amount that was paid using the paymentmethod referenced by the paymentreference. Technically there can be multiple payments in a paymentjob that have brought together the amount paid in total.

Tokenization

Credit cards can be tokenized and saved for easy re-use later.

In order to offer the customer to store his or her credit card, a customer reference should be provided when creating a payment job. The customer can then choose to store his or her credit card as token by checking the corresponding check box on the credit card payment page.

If the customer ever places a second order, he will be provided with the option to use (one of) his previously stored credit card(s) without having to re-enter all of the credit card details.

Supported payment methods

Retrieve supported payment methods

Retrieves a list of supported payment methods for the given configuration.

This function is typically used to generate a payment selection section on your checkout page. Implementing this function makes your checkout page future proof as all details needed to display the offered paymentmethods are there including logo's surcharges etc.

NOTE: if you don't supply a collectamount the function will still return pamentmethodinfo but of course no surcharges will be calculated. A warning will be returned that the collectamount query parameter is missing.

If you supply a customerreference a lookup is made to collect any tokenized creditcards that can be used to perform payments on behalf ot that customer

Query parameters

Key Mandatory Type Remark
collectamount No* string/decimal Decimal separator: . Mandatory if currency is provided.
currency No* string/ECurrency Mandatory if collectamount is provided.
customerreference no string/int64 Set this parameter to receive a list of tokenized credit cards (if any) alongside the supported payment methods
all No bool Set to true (or 1) to retrieve a full list including disabled payment methods.
locale No string/ELocale

Header parameters

Key Mandatory Type Remark
terminalId Yes string
hash Yes string Hexadecimal SHA512 hash of password + body

Possible success response codes

Code Description Response body
200 Supported payment methods retrieved Response object

On success the response object contains an array of PaymentMethodInfo in the data section.

Possible error response codes

Code Description Response body
400 Invalid request Response object
401 Unauthorized Response object
406 Request is not acceptable Response object
503 Service is (partially) unavailable
504 Gateway timed out
500 Internal server error
GET
/api/gateway/supported-payment-methods

Request example

<?php

echo "Starting\n";

require __DIR__ . '/vendor/autoload.php';

// Prepare an executor instance
$execute = new \PaymentGateway\Executor("12345","DE6DA27F-ACFC-463B-91F7-F852FEAC257C","https://gatewayendpoint.example.com");


// Excecute
$execute->callEndPoint("/api/gateway/supported-payment-methods?locale=en_GB&collectamount=100&currency=EUR&customerreference=190729017330868224","GET");

// Analyze result
if ($execute->isSuccess())
{
    $result = new \PaymentGateway\Api\SupportedPaymentMethods\GetResponse();
    $execute->getMappedResponse($result);
    $available  = $result->getData();

    foreach ($available as $paymentMethod)
    {
        var_dump($paymentMethod);
        Var_dump($result->getErrorReport());
    }
}
else
{
    if ($execute->isCurlError())
    {
        var_dump($execute->getCurlError());
        return;
    }
    $result = $execute->getHttpCode() . "[" . $execute->getResponseBody() . "]";
    var_dump($result);
}

echo "Complete";

Response object

{
    "data": [
        {
            "paymentMethod": "Creditcard",
            "logo": {
                "src": "https://secure-dev.paycheckout.com/assets/payment-method-creditcard.png",
        		"src2x": "https://secure-dev.paycheckout.com/assets/payment-method-creditcard@2x.png"
            },
            "supportsTokenization": true,
            "tokenizedCreditCards": [
                {
                    "cardExpiryMonth": "02",
                    "cardExpiryYear": "20",
                    "truncatedCardNumber": "400000****0002"
                },
                {
                    "cardExpiryMonth": "02",
                    "cardExpiryYear": "20",
                    "truncatedCardNumber": "400000****0002"
                },
                {
                    "cardExpiryMonth": "02",
                    "cardExpiryYear": "20",
                    "truncatedCardNumber": "400000****0002"
                },
                {
                    "cardExpiryMonth": "02",
                    "cardExpiryYear": "20",
                    "truncatedCardNumber": "400000****0002"
                },
                {
                    "cardExpiryMonth": "02",
                    "cardExpiryYear": "20",
                    "truncatedCardNumber": "400000****0002"
                },
                {
                    "cardExpiryMonth": "02",
                    "cardExpiryYear": "20",
                    "truncatedCardNumber": "400000****0002"
                }
            ],
            "currencies": [
                "GBP",
                "EUR",
                "USD"
            ],
            "surchargeAmount": "0",
            "surchargeAmountExclVat": "0",
            "surchargeAmountVat": "0",
            "surchargeVatPercentage": "0",
            "description": "Creditcard Simulator"
        },
        {
            "paymentMethod": "Ideal",
            "logo": {
                "src": "https://secure-dev.paycheckout.com/assets/payment-method-ideal.png",
        		"src2x": "https://secure-dev.paycheckout.com/assets/payment-method-ideal@2x.png"
            },
            "issuerList": [
                {
                    "id": "TRIONL2U",
                    "name": "Triodos Bank"
                },
                {
                    "id": "RBRBNL21",
                    "name": "RegioBank"
                },
                {
                    "id": "KNABNL2H",
                    "name": "Knab"
                },
                {
                    "id": "ASNBNL21",
                    "name": "ASN Bank"
                },
                {
                    "id": "SNSBNL2A",
                    "name": "SNS"
                },
                {
                    "id": "RABONL2U",
                    "name": "Rabobank"
                },
                {
                    "id": "INGBNL2A",
                    "name": "ING"
                },
                {
                    "id": "ABNANL2A",
                    "name": "ABN AMRO"
                },
                {
                    "id": "FVLBNL22",
                    "name": "Van Lanschot"
                },
                {
                    "id": "BUNQNL2A",
                    "name": "bunq"
                },
                {
                    "id": "MOYONL21",
                    "name": "Moneyou"
                }
            ],
            "supportsTokenization": false,
            "currencies": [
                "EUR"
            ],
            "surchargeAmount": "0.25",
            "surchargeAmountExclVat": "0.25",
            "surchargeAmountVat": "0.00",
            "surchargeVatPercentage": "0",
            "description": "iDEAL Simulator"
        },
        {
            "paymentMethod": "PayPal",
            "logo": {
                "src": "https://secure-dev.paycheckout.com/assets/payment-method-paypal.png",
        		"src2x": "https://secure-dev.paycheckout.com/assets/payment-method-paypal@2x.png"
            },
            "supportsTokenization": false,
            "currencies": [
                "GBP",
                "EUR",
                "USD"
            ],
            "surchargeAmount": "1.50",
            "surchargeAmountExclVat": "1.50",
            "surchargeAmountVat": "0.00",
            "surchargeVatPercentage": "0",
            "description": "PayPal Simulator"
        }
    ]
}

Payment jobs

Below are all the API calls needed to implement a payment solution

Create a payment job

Query parameters

Key Mandatory Type Remark
locale No string/ELocale

Header parameters

Key Mandatory Type Remark
terminalId Yes string
hash Yes string Hexadecimal SHA512 hash of password + body

Request body properties

Property Mandatory Type Remark
type No string/EPaymentType If omitted, type 'Payment' is used.
currency Yes string/ECurrency
amountToCollect Yes string/decimal Decimal seperator: .
paymentMethodsToUse No array[string/EPaymentMethod] Can only be supplied if no reference to recurring payment job was supplied
parentPaymentJobReference No string Use success payment from this "master" payment to perform payment
expirationDateTimeUtc No string/date-time
diplayUrl No string
terminalMetaData No string
locale Yes string/ELocale
parameters No Parameters
options No array[string/EPaymentJobOption]
order No Order
order.orderNumber No string
order.note No string
order.billingAddress No Address
order.billingAddress.title No string
order.billingAddress.firstName No* string * = This field is mandatory if the EPaymentJobOption StoreCustomerInformation is set.
order.billingAddress.middleName No string
order.billingAddress.lastName No* string * = This field is mandatory if the EPaymentJobOption StoreCustomerInformation is set.
order.billingAddress.countryIso3166Alpha2 No string/ECountry
order.billingAddress.addressLine1 No string
order.billingAddress.addressLine2 No string
order.billingAddress.zipCode No string
order.billingAddress.city No string
order.billingAddress.stateProvince No string
order.billingAddress.phoneNumber1 No string
order.billingAddress.phoneNumber1Type No string/EPhoneNumberType
order.billingAddress.phoneNumber2 No string
order.billingAddress.phoneNumber2Type No string/EPhoneNumberType
order.billingAddress.organisation No string
order.billingAddress.department No string
order.billingIdentity No Identity
order.billingIdentity.debtorId No string
order.billingIdentity.emailAddress No string
order.billingIdentity.gender No string/EGender
order.billingIdentity.dateOfBirth No string/date-time
order.billingIdentity.socialSecurityNumber No string
order.billingIdentity.chamberOfCommerceNumber No string
order.billingIdentity.vatNumber No string
order.shippingAddress No Address
order.shippingAddress.title No string
order.shippingAddress.firstName No string
order.shippingAddress.middleName No string
order.shippingAddress.lastName No string
order.shippingAddress.countryIso3166Alpha2 No string/ECountry
order.shippingAddress.addressLine1 No string
order.shippingAddress.addressLine2 No string
order.shippingAddress.zipCode No string
order.shippingAddress.city No string
order.shippingAddress.stateProvince No string
order.shippingAddress.phoneNumber1 No string
order.shippingAddress.phoneNumber1Type No string/EPhoneNumberType
order.shippingAddress.phoneNumber2 No string
order.shippingAddress.phoneNumber2Type No string/EPhoneNumberType
order.shippingAddress.organisation No string
order.shippingAddress.department No string
order.orderLines No array[OrderLine]
order.orderLines[*].lineNumber Yes string
order.orderLines[*].type Yes string/EOrderLineType
order.orderLines[*].skuCode No string
order.orderLines[*].name Yes string
order.orderLines[*].description No string
order.orderLines[*].quantity Yes string
order.orderLines[*].unitPriceExclVat Yes* string * = Either one or both unit prices must be specified.
order.orderLines[*].unitPriceInclVat Yes* string * = Either one or both unit prices must be specified.
order.orderLines[*].vatPercentage No string
order.orderLines[*].vatPercentageLabel No string
order.orderLines[*].discountPercentageLabel No string
order.orderLines[*].totalLineAmount Yes string
order.orderLines[*].url No string

Possible success response codes

Code Description Response body
201 Payment job created Response object

On success the response object contains the created PaymentJob in the data section.

Possible error response codes

Code Description Response body
400 Invalid request Response object
401 Unauthorized Response object
406 Request was not acceptable Response object
503 Service is (partially) unavailable
504 Gateway timed out
500 Internal server error
POST
/api/gateway/payment-jobs

Request example

<?php

echo "Starting\n";

require __DIR__ . '/vendor/autoload.php';

// Create an executor instance
$execute = new \PaymentGateway\Executor("12345","DE6DA27F-ACFC-463B-91F7-F852FEAC257C","https://gatewayendpoint.example.com");

// Prepare order
$order = new \PaymentGateway\Model\Order\Order();
$order->setOrderNumber("2019-03-18/1001");
$order->setBillingIdentity(new \PaymentGateway\Model\Identity());
$order->setBillingAddress(new \PaymentGateway\Model\Address());
$order->setShippingAddress(new \PaymentGateway\Model\Address());

// Prepare identity
$order->getBillingIdentity()->setDebtorId("debtorId");
$order->getBillingIdentity()->setEmailAddress("John.Doe@example.com");
$order->getBillingIdentity()->setGender(\PaymentGateway\Model\Gender::Male);

// Prepare addresses
$order->getBillingAddress()->setTitle("Mr.");
$order->getBillingAddress()->setFirstName("John");
$order->getBillingAddress()->setMiddleName("Van");
$order->getBillingAddress()->setLastName("Dijk");
$order->getBillingAddress()->setOrganisation("Sample Business Ltd");
$order->getBillingAddress()->setAddressLine1("Business Centre Road");
$order->getBillingAddress()->setAddressLine2("Unit 7");
$order->getBillingAddress()->setZIPCode("XX12 1XX");
$order->getBillingAddress()->setCity("TestCity");
$order->getBillingAddress()->setPhoneNumber1("+44 9999 123456");
$order->getBillingAddress()->setPhoneNumber1Type(\PaymentGateway\Model\PhoneNumberType::Fixed);
$order->getBillingAddress()->setPhoneNumber2("+44 8888 123456");
$order->getBillingAddress()->setPhoneNumber2Type(\PaymentGateway\Model\PhoneNumberType::Unknown);
$order->getBillingAddress()->setCountryISO3166Alpha2("GB");

// Prepare addresses
$order->getShippingAddress()->setTitle("Mr.");
$order->getShippingAddress()->setFirstName("John");
$order->getShippingAddress()->setLastName("Doe");
$order->getShippingAddress()->setOrganisation("TestCompany");
$order->getShippingAddress()->setAddressLine1("Addressline1");
$order->getShippingAddress()->setAddressLine2("Addressline2");
$order->getShippingAddress()->setZIPCode("XX21 5XX");
$order->getShippingAddress()->setCity("Cambridge");
$order->getShippingAddress()->setPhoneNumber1("+44 9999 000000");
$order->getShippingAddress()->setPhoneNumber1Type(\PaymentGateway\Model\PhoneNumberType::Fixed);
$order->getShippingAddress()->setCountryISO3166Alpha2("GB");

// Add orderline
$orderline = new \PaymentGateway\Model\Order\OrderLine();
$orderline->setLineNumber("1");
$orderline->setType(\PaymentGateway\Model\Order\OrderLineType::PhysicalItem);
$orderline->setSkuCode("1234567890123");
$orderline->setName("Bike");
$orderline->setQuantity(1.1);
$orderline->setUnitPriceExclVat(100);
$orderline->setUnitPriceInclVat(121);
$orderline->setVatPercentage(21);
$orderline->setVatPercentageLabel("Vat 21%");
$orderline->setDiscountPercentageLabel("discount 6%");
$orderline->setTotalLineAmount(121);
$order->addOrderline($orderline);

// Prepare PostRequest
$postRequest = new \PaymentGateway\Api\PaymentJobs\PostRequest();
$postRequest->setLocale(\PaymentGateway\Model\Locale::en_GB);
$postRequest->setOrder($order);
$postRequest->setAmountToCollect(121);
$postRequest->setCurrency(\PaymentGateway\Model\Currency::GBP);
$postRequest->addPaymentMethod(\PaymentGateway\Model\PaymentMethod::Creditcard);
$postRequest->addPaymentMethod(\PaymentGateway\Model\PaymentMethod::PayPal);
$postRequest->addOption(\PaymentGateway\Api\PaymentJobs\PaymentJobOption::StoreCustomerInformation);
$postRequest->addAttribute(\PaymentGateway\Model\PaymentJob\PaymentJobAttribute::webhookUrl,"https://www.example.com");
$postRequest->addParameter(\PaymentGateway\Api\PaymentJobs\PaymentJobParameter::returnUrlSuccess,"https://www.example.com?status=success");
$postRequest->addParameter(\PaymentGateway\Api\PaymentJobs\PaymentJobParameter::returnUrlCancelled,"https://www.example.com?status=cancelled");
$postRequest->addParameter(\PaymentGateway\Api\PaymentJobs\PaymentJobParameter::returnUrlFailed,"https://www.example.com?status=failed");

// Execute the call
$execute->callEndPoint("/api/gateway/payment-jobs","POST",$postRequest);

// Analyze result
if ($execute->isSuccess())
{
    $result = new \PaymentGateway\Api\PaymentJobs\PostResponse();
    $execute->getMappedResponse($result);
    var_dump($result);
}
else
{
    if ($execute->isCurlError())
    {
        var_dump($execute->getCurlError());
        return;
    }
    $result = $execute->getHttpCode() . "[" . $execute->getResponseBody() . "]";
    var_dump($result);
}

echo "Complete";

Request body

{
  "parameters": {
    "returnUrlSuccess": "https:\/\/www.example.com?status=success",
    "returnUrlCancelled": "https:\/\/www.example.com?status=cancelled",
    "returnUrlFailed": "https:\/\/www.example.com?status=failed"
  },
  "options": [
    "storeCustomerInformation"
  ],
  "locale": "en_GB",
  "order": {
    "orderNumber": "2019-03-18\/1001",
    "billingAddress": {
      "title": "Mr.",
      "firstName": "John",
      "middleName": "Van",
      "lastName": "Dijk",
      "countryIso3166Alpha2": "GB",
      "addressLine1": "Business Centre Road",
      "addressLine2": "Unit 7",
      "zipCode": "XX12 1XX",
      "city": "TestCity",
      "phoneNumber1": "+44 9999 123456",
      "phoneNumber1Type": "Fixed",
      "phoneNumber2": "+44 8888 123456",
      "phoneNumber2Type": "Unknown",
      "organisation": "Sample Business Ltd"
    },
    "billingIdentity": {
      "debtorId": "debtorId",
      "emailAddress": "John.Doe@example.com",
      "gender": "Male"
    },
    "shippingAddress": {
      "title": "Mr.",
      "firstName": "John",
      "lastName": "Doe",
      "countryIso3166Alpha2": "GB",
      "addressLine1": "Addressline1",
      "addressLine2": "Addressline2",
      "zipCode": "XX21 5XX",
      "city": "Cambridge",
      "phoneNumber1": "+44 9999 000000",
      "phoneNumber1Type": "Fixed",
      "organisation": "TestCompany"
    },
    "orderLines": [
      {
        "lineNumber": "1",
        "type": "PhysicalItem",
        "skuCode": "1234567890123",
        "name": "Bike",
        "quantity": "1.1",
        "unitPriceExclVat": "100",
        "unitPriceInclVat": "121",
        "vatPercentage": "21",
        "vatPercentageLabel": "Vat 21%",
        "discountPercentageLabel": "discount 6%",
        "totalLineAmount": "121"
      }
    ]
  },
  "paymentMethodsToUse": [
    "Creditcard",
    "PayPal"
  ],
  "currency": "GBP",
  "amountToCollect": "121",
  "attributes": {
    "webhookUrl": "https:\/\/www.example.com"
  }
}

Response object

{
    "data": {
        "reference": "190721000461508616",
        "createDateTimeUtc": "2019-07-12T10:22:04.180365Z",
        "type": "Payment",
        "traceReference": "190720104714528772",
        "terminalId": "12345",
        "domain": "paycheckout.com",
        "locale": "en_GB",
        "order": {
            "orderNumber": "2019-03-18/1001",
            "createDateTimeUtc": "2019-07-12T10:22:04.1803388Z",
            "customerReference": "190729000042078216",
            "billingAddress": {
                "title": "Mr.",
                "firstName": "John",
                "middleName": "Van",
                "lastName": "Dijk",
                "countryIso3166Alpha2": "GB",
                "addressLine1": "Business Centre Road",
                "addressLine2": "Unit 7",
                "zipCode": "XX12 1XX",
                "city": "TestCity",
                "phoneNumber1": "+44 9999 123456",
                "phoneNumber1Type": "Fixed",
                "phoneNumber2": "+44 8888 123456",
                "phoneNumber2Type": "Unknown",
                "organisation": "Sample Business Ltd"
            },
            "billingIdentity": {
                "debtorId": "debtorId",
                "emailAddress": "John.Doe@example.com",
                "gender": "Male"
            },
            "shippingAddress": {
                "title": "Mr.",
                "firstName": "John",
                "lastName": "Doe",
                "countryIso3166Alpha2": "GB",
                "addressLine1": "Addressline1",
                "addressLine2": "Addressline2",
                "zipCode": "XX21 5XX",
                "city": "Cambridge",
                "phoneNumber1": "+44 9999 000000",
                "phoneNumber1Type": "Fixed",
                "organisation": "TestCompany"
            },
            "orderLines": [
                {
                    "lineNumber": "1",
                    "type": "PhysicalItem",
                    "skuCode": "1234567890123",
                    "name": "Bike",
                    "quantity": "1.1",
                    "unitPriceExclVat": "100",
                    "unitPriceInclVat": "121",
                    "vatPercentage": "21",
                    "vatPercentageLabel": "Vat 21%",
                    "discountPercentageLabel": "discount 6%",
                    "totalLineAmount": "121"
                }
            ]
        },
        "paymentMethodsToUse": [
            "Creditcard",
            "PayPal"
        ],
        "currency": "GBP",
        "amountToCollect": "121",
        "expirationDateTimeUtc": "2020-01-12T10:22:04.1803632Z",
        "dueDateTimeUtc": "2019-07-12T11:22:04.1803666Z",
        "lastSeenTimeUtc": "2019-07-12T10:22:04.1803666Z",
        "lastProcessedTimeUtc": "2019-07-12T10:22:04.1803659Z",
        "attributes": {
            "webhookUrl": "http://internal-dev-private-165961934.eu-west-1.elb.amazonaws.com/notifier/api/notifier-test"
        },
        "paymentStatus": "Pending",
        "payments": [
            {
                "reference": "190721100444600320",
                "createDateTimeUtc": "2019-07-12T10:22:04.4395345Z",
                "paymentMethods": [
                    "Creditcard",
                    "PayPal"
                ],
                "status": "Pending",
                "abuseReport": {
                  "score": "46",
                  "triggers": [
                    {
                      "score": "0",
                      "code": "I",
                      "description": "Internet inconsistencies. The IP address and email domain are not consistent with the billing address.",
                      "parameters": []
                    },
                    {
                      "score": "0",
                      "code": "Q",
                      "description": "Phone inconsistencies. The customer’s phone number is suspicious.",
                      "parameters": []
                    },
                    {
                      "score": "0",
                      "code": "V",
                      "description": "Velocity. The account number was used many times in the past 15 minutes.",
                      "parameters": []
                    },
                    {
                      "score": "0",
                      "code": "COR-BA",
                      "description": "The billing address has corrected elements or can be normalized.",
                      "parameters": []
                    },
                    {
                      "score": "0",
                      "code": "INTL-BA",
                      "description": "The billing country is outside of the U.S.",
                      "parameters": []
                    },
                    {
                      "score": "0",
                      "code": "INTL-SA",
                      "description": "The shipping country is outside of the U.S.",
                      "parameters": []
                    },
                    {
                      "score": "0",
                      "code": "VELL-IP",
                      "description": "The IP address has been used several times during the long tracking interval.",
                      "parameters": []
                    },
                    {
                      "score": "0",
                      "code": "VELL-SA",
                      "description": "The shipping address has been used several times during the long tracking interval.",
                      "parameters": []
                    },
                    {
                      "score": "0",
                      "code": "VELV-IP",
                      "description": "The IP address has been used several times during the very long tracking interval.",
                      "parameters": []
                    },
                    {
                      "score": "0",
                      "code": "VELV-SA",
                      "description": "The shipping address has been used several times during the very long tracking interval.",
                      "parameters": []
                    },
                    {
                      "score": "0",
                      "code": "INTL-IPCO",
                      "description": "The country of the customer’s IP address is outside of the U.S.",
                      "parameters": []
                    },
                    {
                      "score": "46",
                      "code": "CS_GLOBAL",
                      "description": "Global score from CyberSource.",
                      "parameters": []
                    }
                  ],
                  "createdDateTimeUtc": "2019-08-23T09:53:45.188Z"
                },
                "amountToCollect": "121",
                "steps": [
                    {
                        "reference": "190721221516783620",
                        "createDateTimeUtc": "2019-07-12T10:22:04.4399625Z",
                        "action": "DisplayHostedPage",
                        "paymentMethods": [
                            "Creditcard",
                            "PayPal"
                        ],
                        "status": "Pending",
                        "amountToCollect": "121"
                    }
                ],
                "attributes": {
                    "returnUrlSuccess": "https://www.example.com?status=success&paymentjobref=190721000461508616&paymentref=190721100444600320&ordernumber=2019-03-18%2f1001",
                    "returnUrlFailed": "https://www.example.com?status=failed&paymentjobref=190721000461508616&paymentref=190721100444600320&ordernumber=2019-03-18%2f1001",
                    "returnUrlCancelled": "https://www.example.com?status=cancelled&status=cancelled&paymentjobref=190721000461508616&paymentref=190721100444600320&ordernumber=2019-03-18%2f1001"
                }
            }
        ]
    },
    "links": {
        "data": {
            "url": "https://secure-dev.paycheckout.com/api/gateway/payment-jobs/190721000461508616",
            "type": "application/json"
        },
        "action": {
            "url": "https://secure-dev.paycheckout.com/payment?ref=4d28fe4d70398af4c041eaadd657e605bcaed35422030a70dd593a834b04d61dd7bad0fa073af78290f56fd7c994b7c2",
            "type": "text/html"
        }
    }
}

Retrieve a payment job

This api call is used to retrieve a paymentjob on its known paymentjob reference.

Query parameters

Key Mandatory Type Remark
locale No string/ELocale

Header parameters

Key Mandatory Type Remark
terminalId Yes string
hash Yes string Hexadecimal SHA512 hash of password + body

Possible success response codes

Code Description Response body
200 Payment job retrieved Response object

On success the response object contains the retrieved PaymentJob in the data section.

Possible error response code

Code Description Response body
400 Invalid request Response object
401 Unauthorized Response object
404 Payment job not found Response object
406 Request was not acceptable Response object
503 Service is (partially) unavailable
504 Gateway timed out
500 Internal server error
GET
/api/gateway/payment-jobs/{PaymentJobReference}

Request example

<?php

echo "Starting\n";

require __DIR__ . '/vendor/autoload.php';

// Create an executor instance
$execute = new \PaymentGateway\Executor("12345","DE6DA27F-ACFC-463B-91F7-F852FEAC257C","https://gatewayendpoint.example.com");

// Set the paymentjob reference you want to retrieve
$ref = '190721000461508616';

// Now perform get 
$execute->callEndPoint("/api/gateway/payment-jobs/" . $ref . "?locale=NL_nl" ,"GET");

// Analyze result
if ($execute->isSuccess())
{
    $result = new \PaymentGateway\Api\PaymentJobs\GetResponse();
    $execute->getMappedResponse($result);
    $available  = $result->getData();
    var_dump($available);
    var_dump($available->getPayments()[0]);
}
else
{
    if ($execute->isCurlError())
    {
        var_dump($execute->getCurlError());
        return;
    }
    $result = $execute->getHttpCode() . "[" . $execute->getResponseBody() . "]";
    var_dump($result);
}
echo "Complete";

Response object

{
    "data": {
        "reference": "190721000461508616",
        "createDateTimeUtc": "2019-07-12T10:22:04.18Z",
        "type": "Payment",
        "traceReference": "190720104714528772",
        "terminalId": "12345",
        "domain": "paycheckout.com",
        "locale": "en_GB",
        "order": {
            "orderNumber": "2019-03-18/1001",
            "createDateTimeUtc": "2019-07-12T10:22:04.18Z",
            "customerReference": "190729000042078216",
            "billingAddress": {
                "title": "Mr.",
                "firstName": "John",
                "middleName": "Van",
                "lastName": "Dijk",
                "countryIso3166Alpha2": "GB",
                "addressLine1": "Business Centre Road",
                "addressLine2": "Unit 7",
                "zipCode": "XX12 1XX",
                "city": "TestCity",
                "phoneNumber1": "+44 9999 123456",
                "phoneNumber1Type": "Fixed",
                "phoneNumber2": "+44 8888 123456",
                "phoneNumber2Type": "Unknown",
                "organisation": "Sample Business Ltd"
            },
            "billingIdentity": {
                "debtorId": "debtorId",
                "emailAddress": "John.Doe@example.com",
                "gender": "Male"
            },
            "shippingAddress": {
                "title": "Mr.",
                "firstName": "John",
                "lastName": "Doe",
                "countryIso3166Alpha2": "GB",
                "addressLine1": "Addressline1",
                "addressLine2": "Addressline2",
                "zipCode": "XX21 5XX",
                "city": "Cambridge",
                "phoneNumber1": "+44 9999 000000",
                "phoneNumber1Type": "Fixed",
                "organisation": "TestCompany"
            },
            "orderLines": [
                {
                    "lineNumber": "1",
                    "type": "PhysicalItem",
                    "skuCode": "1234567890123",
                    "name": "Bike",
                    "quantity": "1.1",
                    "unitPriceExclVat": "100",
                    "unitPriceInclVat": "121",
                    "vatPercentage": "21",
                    "vatPercentageLabel": "Vat 21%",
                    "discountPercentageLabel": "discount 6%",
                    "totalLineAmount": "121"
                }
            ]
        },
        "paymentMethodsToUse": [
            "Creditcard",
            "PayPal"
        ],
        "currency": "GBP",
        "amountToCollect": "121",
        "expirationDateTimeUtc": "2020-01-12T10:22:04.18Z",
        "lastSeenTimeUtc": "2019-07-12T10:22:04.18Z",
        "lastProcessedTimeUtc": "2019-07-12T11:22:17.452Z",
        "flags": {
            "secondChanceEmailSent": true
        },
        "attributes": {
            "webhookUrl": "http://internal-dev-private-165961934.eu-west-1.elb.amazonaws.com/notifier/api/notifier-test"
        },
        "paymentStatus": "Pending",
        "payments": [
            {
                "reference": "190721100444600320",
                "createDateTimeUtc": "2019-07-12T10:22:04.439Z",
                "paymentMethods": [
                    "Creditcard",
                    "PayPal"
                ],
                "status": "Pending",
                "abuseReport": {
                  "score": "46",
                  "triggers": [
                    {
                      "score": "0",
                      "code": "I",
                      "description": "Internet inconsistencies. The IP address and email domain are not consistent with the billing address.",
                      "parameters": []
                    },
                    {
                      "score": "0",
                      "code": "Q",
                      "description": "Phone inconsistencies. The customer’s phone number is suspicious.",
                      "parameters": []
                    },
                    {
                      "score": "0",
                      "code": "V",
                      "description": "Velocity. The account number was used many times in the past 15 minutes.",
                      "parameters": []
                    },
                    {
                      "score": "0",
                      "code": "COR-BA",
                      "description": "The billing address has corrected elements or can be normalized.",
                      "parameters": []
                    },
                    {
                      "score": "0",
                      "code": "INTL-BA",
                      "description": "The billing country is outside of the U.S.",
                      "parameters": []
                    },
                    {
                      "score": "0",
                      "code": "INTL-SA",
                      "description": "The shipping country is outside of the U.S.",
                      "parameters": []
                    },
                    {
                      "score": "0",
                      "code": "VELL-IP",
                      "description": "The IP address has been used several times during the long tracking interval.",
                      "parameters": []
                    },
                    {
                      "score": "0",
                      "code": "VELL-SA",
                      "description": "The shipping address has been used several times during the long tracking interval.",
                      "parameters": []
                    },
                    {
                      "score": "0",
                      "code": "VELV-IP",
                      "description": "The IP address has been used several times during the very long tracking interval.",
                      "parameters": []
                    },
                    {
                      "score": "0",
                      "code": "VELV-SA",
                      "description": "The shipping address has been used several times during the very long tracking interval.",
                      "parameters": []
                    },
                    {
                      "score": "0",
                      "code": "INTL-IPCO",
                      "description": "The country of the customer’s IP address is outside of the U.S.",
                      "parameters": []
                    },
                    {
                      "score": "46",
                      "code": "CS_GLOBAL",
                      "description": "Global score from CyberSource.",
                      "parameters": []
                    }
                  ],
                  "createdDateTimeUtc": "2019-08-23T09:53:45.188Z"
                },
                "amountToCollect": "121",
                "steps": [
                    {
                        "reference": "190721221516783620",
                        "createDateTimeUtc": "2019-07-12T10:22:04.439Z",
                        "action": "DisplayHostedPage",
                        "paymentMethods": [
                            "Creditcard",
                            "PayPal"
                        ],
                        "status": "Pending",
                        "amountToCollect": "121"
                    }
                ],
                "attributes": {
                    "returnUrlSuccess": "https://www.example.com?status=success&paymentjobref=190721000461508616&paymentref=190721100444600320&ordernumber=2019-03-18%2f1001",
                    "returnUrlFailed": "https://www.example.com?status=failed&paymentjobref=190721000461508616&paymentref=190721100444600320&ordernumber=2019-03-18%2f1001",
                    "returnUrlCancelled": "https://www.example.com?status=cancelled&status=cancelled&paymentjobref=190721000461508616&paymentref=190721100444600320&ordernumber=2019-03-18%2f1001"
                }
            }
        ]
    },
    "errorReport": {
        "errors": [
            {
                "code": "NotExactMatch_2",
                "message": "Hash has value [0BE19A2DD9A5EB99651E85ED26C5C7C5099C0264F6C257432CB53AB9C168D9895F23040F7BAD48340BFB4A5025265FD83FF0A9EA3289E88408729DAAC4B20860] which does not match the expected value.",
                "parameters": [
                    "Hash",
                    "0BE19A2DD9A5EB99651E85ED26C5C7C5099C0264F6C257432CB53AB9C168D9895F23040F7BAD48340BFB4A5025265FD83FF0A9EA3289E88408729DAAC4B20860"
                ]
            }
        ],
        "isFatalError": true
    }
}

Cancel a payment job

This call can be used to cancel a paymentjob which has not received any funds yet. On success the paymentstatus will be set to "Cancelled". When the status of paymentjob is cancelled the paymentjob will refuse all payment attempts.

Query parameters

Key Mandatory Type Remark
locale No string/ELocale

Header parameters

Key Mandatory Type Remark
terminalId Yes string
hash Yes string Hexadecimal SHA512 hash of password + body

Possible success response codes

Code Description Response body
200 Payment job cancelled Response object

On success the response object contains the cancelled PaymentJob in the data section.

Possible error response codes

Code Description Response body
400 Invalid request Response object
401 Unauthorized Response object
404 Payment job not found Response object
406 Request was not acceptable Response object
503 Service is (partially) unavailable
504 Gateway timed out
500 Internal server error
PATCH
/api/gateway/payment-jobs/{PaymentJobReference}/cancel

Request example

<?php

echo "Starting\n";

require __DIR__ . '/vendor/autoload.php';

// Set executor
$execute = new \PaymentGateway\Executor("12345","DE6DA27F-ACFC-463B-91F7-F852FEAC257C","https://gatewayendpoint.example.com");

// Set reference of paymentjob to cancel
$ref = '190721000461508616';

// Call the endpoint
$execute->callEndPoint("/api/gateway/payment-jobs/" . $ref . "/cancel?locale=NL_nl","PATCH");

// Analyze result
if ($execute->isSuccess())
{
    $response = new \PaymentGateway\Api\PaymentJobs\GetResponse();
    $execute->getMappedResponse($respponse);
    $paymentJob = $response->getData();
    var_dump($paymentJob);
}
else
{
    if ($execute->isCurlError())
    {
        var_dump($execute->getCurlError());
        return;
    }
    $result = $execute->getHttpCode() . "[" . $execute->getResponseBody() . "]";
    var_dump($result);
}

echo "Complete";

Response object

{
    "data": {
        "reference": "190721000461508616",
        "createDateTimeUtc": "2019-07-12T10:22:04.18Z",
        "type": "Payment",
        "traceReference": "190720104714528772",
        "terminalId": "12345",
        "domain": "paycheckout.com",
        "locale": "en_GB",
        "order": {
            "orderNumber": "2019-03-18/1001",
            "createDateTimeUtc": "2019-07-12T10:22:04.18Z",
            "customerReference": "190729000042078216",
            "billingAddress": {
                "title": "Mr.",
                "firstName": "John",
                "middleName": "Van",
                "lastName": "Dijk",
                "countryIso3166Alpha2": "GB",
                "addressLine1": "Business Centre Road",
                "addressLine2": "Unit 7",
                "zipCode": "XX12 1XX",
                "city": "TestCity",
                "phoneNumber1": "+44 9999 123456",
                "phoneNumber1Type": "Fixed",
                "phoneNumber2": "+44 8888 123456",
                "phoneNumber2Type": "Unknown",
                "organisation": "Sample Business Ltd"
            },
            "billingIdentity": {
                "debtorId": "debtorId",
                "emailAddress": "John.Doe@example.com",
                "gender": "Male"
            },
            "shippingAddress": {
                "title": "Mr.",
                "firstName": "John",
                "lastName": "Doe",
                "countryIso3166Alpha2": "GB",
                "addressLine1": "Addressline1",
                "addressLine2": "Addressline2",
                "zipCode": "XX21 5XX",
                "city": "Cambridge",
                "phoneNumber1": "+44 9999 000000",
                "phoneNumber1Type": "Fixed",
                "organisation": "TestCompany"
            },
            "orderLines": [
                {
                    "lineNumber": "1",
                    "type": "PhysicalItem",
                    "skuCode": "1234567890123",
                    "name": "Bike",
                    "quantity": "1.1",
                    "unitPriceExclVat": "100",
                    "unitPriceInclVat": "121",
                    "vatPercentage": "21",
                    "vatPercentageLabel": "Vat 21%",
                    "discountPercentageLabel": "discount 6%",
                    "totalLineAmount": "121"
                }
            ]
        },
        "paymentMethodsToUse": [
            "Creditcard",
            "PayPal"
        ],
        "currency": "GBP",
        "amountToCollect": "121",
        "expirationDateTimeUtc": "2020-01-12T10:22:04.18Z",
        "lastSeenTimeUtc": "2019-07-12T10:22:04.18Z",
        "lastProcessedTimeUtc": "2019-07-12T11:22:17.452Z",
        "flags": {
            "secondChanceEmailSent": true
        },
        "attributes": {
            "webhookUrl": "http://internal-dev-private-165961934.eu-west-1.elb.amazonaws.com/notifier/api/notifier-test"
        },
        "paymentStatus": "Cancelled",
        "payments": [
            {
                "reference": "190721100444600320",
                "createDateTimeUtc": "2019-07-12T10:22:04.439Z",
                "paymentMethods": [
                    "Creditcard",
                    "PayPal"
                ],
                "status": "Cancelled",
                "abuseReport": {
                  "score": "46",
                  "triggers": [
                    {
                      "score": "0",
                      "code": "I",
                      "description": "Internet inconsistencies. The IP address and email domain are not consistent with the billing address.",
                      "parameters": []
                    },
                    {
                      "score": "0",
                      "code": "Q",
                      "description": "Phone inconsistencies. The customer’s phone number is suspicious.",
                      "parameters": []
                    },
                    {
                      "score": "0",
                      "code": "V",
                      "description": "Velocity. The account number was used many times in the past 15 minutes.",
                      "parameters": []
                    },
                    {
                      "score": "0",
                      "code": "COR-BA",
                      "description": "The billing address has corrected elements or can be normalized.",
                      "parameters": []
                    },
                    {
                      "score": "0",
                      "code": "INTL-BA",
                      "description": "The billing country is outside of the U.S.",
                      "parameters": []
                    },
                    {
                      "score": "0",
                      "code": "INTL-SA",
                      "description": "The shipping country is outside of the U.S.",
                      "parameters": []
                    },
                    {
                      "score": "0",
                      "code": "VELL-IP",
                      "description": "The IP address has been used several times during the long tracking interval.",
                      "parameters": []
                    },
                    {
                      "score": "0",
                      "code": "VELL-SA",
                      "description": "The shipping address has been used several times during the long tracking interval.",
                      "parameters": []
                    },
                    {
                      "score": "0",
                      "code": "VELV-IP",
                      "description": "The IP address has been used several times during the very long tracking interval.",
                      "parameters": []
                    },
                    {
                      "score": "0",
                      "code": "VELV-SA",
                      "description": "The shipping address has been used several times during the very long tracking interval.",
                      "parameters": []
                    },
                    {
                      "score": "0",
                      "code": "INTL-IPCO",
                      "description": "The country of the customer’s IP address is outside of the U.S.",
                      "parameters": []
                    },
                    {
                      "score": "46",
                      "code": "CS_GLOBAL",
                      "description": "Global score from CyberSource.",
                      "parameters": []
                    }
                  ],
                  "createdDateTimeUtc": "2019-08-23T09:53:45.188Z"
                },
                "amountToCollect": "121",
                "steps": [
                    {
                        "reference": "190721221516783620",
                        "createDateTimeUtc": "2019-07-12T10:22:04.439Z",
                        "action": "DisplayHostedPage",
                        "paymentMethods": [
                            "Creditcard",
                            "PayPal"
                        ],
                        "status": "Pending",
                        "amountToCollect": "121"
                    }
                ],
                "attributes": {
                    "returnUrlSuccess": "https://www.example.com?status=success&paymentjobref=190721000461508616&paymentref=190721100444600320&ordernumber=2019-03-18%2f1001",
                    "returnUrlFailed": "https://www.example.com?status=failed&paymentjobref=190721000461508616&paymentref=190721100444600320&ordernumber=2019-03-18%2f1001",
                    "returnUrlCancelled": "https://www.example.com?status=cancelled&status=cancelled&paymentjobref=190721000461508616&paymentref=190721100444600320&ordernumber=2019-03-18%2f1001"
                }
            }
        ]
    }
}

Payments

In the section below the API calls are described that can act on payments

Retrieve a payment

Retrieve a payment, addressing it by its paymentjob reference and payment reference.

Query parameters

Key Mandatory Type Remark
locale No string/ELocale

Header parameters

Key Mandatory Type Remark
terminalId Yes string
hash Yes string Hexadecimal SHA512 hash of password + body

Possible success response codes

Code Description Response body
200 Payment job retrieved Response object

On success the response object contains the retrieved Payment in the data section.

Possible error response codes

Code Description Response body
400 Invalid request Response object
401 Unauthorized Response object
404 Payment or payment job not found Response object
406 Request was not acceptable Response object
503 Service is (partially) unavailable
504 Gateway timed out
500 Internal server error
GET
/api/gateway/payment-jobs/{PaymentJobReference}/payments/{PaymentReference}

Request example

<?php

echo "Starting\n";

require __DIR__ . '/vendor/autoload.php';

// Create an executor
$execute = new \PaymentGateway\Executor("12345","DE6DA27F-ACFC-463B-91F7-F852FEAC257C","https://gatewayendpoint.example.com");

$jobref   = '190721000461508616';
$payref   = '190721100444600320';

// Execute the get payment request
$execute->callEndPoint("/api/gateway/payment-jobs/" .$jobref . "/payments/" . $payref . "?locale=NL_nl","GET");

if ($execute->isSuccess())
{
    $response = new \PaymentGateway\Api\PaymentJobs\Payments\GetResponse();
    $execute->getMappedResponse($response);
    $payment  = $response->getData();
    var_dump($payment);
    return;
}
else
{
    if ($execute->isCurlError())
    {
        var_dump($execute->getCurlError());
        return;
    }
    $result = $execute->getHttpCode() . "[" . $execute->getResponseBody() . "]";
    var_dump($result);
}
echo "Complete";

Response object

{
    "data": {
        "reference": "190721100444600320",
        "createDateTimeUtc": "2019-07-12T10:22:04.439Z",
        "paymentMethods": [
            "Creditcard",
            "PayPal"
        ],
        "status": "Cancelled",
        "abuseReport": {
          "score": "46",
          "triggers": [
            {
              "score": "0",
              "code": "I",
              "description": "Internet inconsistencies. The IP address and email domain are not consistent with the billing address.",
              "parameters": []
            },
            {
              "score": "0",
              "code": "Q",
              "description": "Phone inconsistencies. The customer’s phone number is suspicious.",
              "parameters": []
            },
            {
              "score": "0",
              "code": "V",
              "description": "Velocity. The account number was used many times in the past 15 minutes.",
              "parameters": []
            },
            {
              "score": "0",
              "code": "COR-BA",
              "description": "The billing address has corrected elements or can be normalized.",
              "parameters": []
            },
            {
              "score": "0",
              "code": "INTL-BA",
              "description": "The billing country is outside of the U.S.",
              "parameters": []
            },
            {
              "score": "0",
              "code": "INTL-SA",
              "description": "The shipping country is outside of the U.S.",
              "parameters": []
            },
            {
              "score": "0",
              "code": "VELL-IP",
              "description": "The IP address has been used several times during the long tracking interval.",
              "parameters": []
            },
            {
              "score": "0",
              "code": "VELL-SA",
              "description": "The shipping address has been used several times during the long tracking interval.",
              "parameters": []
            },
            {
              "score": "0",
              "code": "VELV-IP",
              "description": "The IP address has been used several times during the very long tracking interval.",
              "parameters": []
            },
            {
              "score": "0",
              "code": "VELV-SA",
              "description": "The shipping address has been used several times during the very long tracking interval.",
              "parameters": []
            },
            {
              "score": "0",
              "code": "INTL-IPCO",
              "description": "The country of the customer’s IP address is outside of the U.S.",
              "parameters": []
            },
            {
              "score": "46",
              "code": "CS_GLOBAL",
              "description": "Global score from CyberSource.",
              "parameters": []
            }
          ],
          "createdDateTimeUtc": "2019-08-23T09:53:45.188Z"
        },
        "amountToCollect": "121",
        "steps": [
            {
                "reference": "190721221516783620",
                "createDateTimeUtc": "2019-07-12T10:22:04.439Z",
                "action": "DisplayHostedPage",
                "paymentMethods": [
                    "Creditcard",
                    "PayPal"
                ],
                "status": "Pending",
                "amountToCollect": "121"
            }
        ],
        "attributes": {
            "returnUrlSuccess": "https://www.example.com?status=success&paymentjobref=190721000461508616&paymentref=190721100444600320&ordernumber=2019-03-18%2f1001",
            "returnUrlFailed": "https://www.example.com?status=failed&paymentjobref=190721000461508616&paymentref=190721100444600320&ordernumber=2019-03-18%2f1001",
            "returnUrlCancelled": "https://www.example.com?status=cancelled&status=cancelled&paymentjobref=190721000461508616&paymentref=190721100444600320&ordernumber=2019-03-18%2f1001"
        }
    },
    "links": {
        "data": {
            "url": "https://secure-dev.paycheckout.com/api/gateway/payment-jobs/190721000461508616/payments/190721100444600320",
            "type": "application/json"
        }
    }
}

Orders

Update an order

Query parameters

Key Mandatory Type Remark
locale No string/ELocale

Header parameters

Key Mandatory Type Remark
terminalId Yes string
hash Yes string Hexadecimal SHA512 hash of password + body

Request body properties

Property Mandatory Type Remark
orderNumber No string
note No string
billingAddress No Address
billingAddress.title No string
billingAddress.firstName No string
billingAddress.middleName No string
billingAddress.lastName No string
billingAddress.countryIso3166Alpha2 No string/ECountry
billingAddress.addressLine1 No string
billingAddress.addressLine2 No string
billingAddress.zipCode No string
billingAddress.city No string
billingAddress.stateProvince No string
billingAddress.phoneNumber1 No string
billingAddress.phoneNumber1Type No string/EPhoneNumberType
billingAddress.phoneNumber2 No string
billingAddress.phoneNumber2Type No string/EPhoneNumberType
billingAddress.organisation No string
billingAddress.department No string
billingIdentity No Identity
billingIdentity.debtorId No string
billingIdentity.emailAddress No string
billingIdentity.gender No string/EGender
billingIdentity.dateOfBirth No string/date-time
billingIdentity.socialSecurityNumber No string
billingIdentity.chamberOfCommerceNumber No string
billingIdentity.vatNumber No string
shippingAddress No Address
shippingAddress.title No string
shippingAddress.firstName No string
shippingAddress.middleName No string
shippingAddress.lastName No string
shippingAddress.countryIso3166Alpha2 No string/ECountry
shippingAddress.addressLine1 No string
shippingAddress.addressLine2 No string
shippingAddress.zipCode No string
shippingAddress.city No string
shippingAddress.stateProvince No string
shippingAddress.phoneNumber1 No string
shippingAddress.phoneNumber1Type No string/EPhoneNumberType
shippingAddress.phoneNumber2 No string
shippingAddress.phoneNumber2Type No string/EPhoneNumberType
shippingAddress.organisation No string
shippingAddress.department No string
orderLines No array[OrderLine]
orderLines[*].lineNumber Yes string
orderLines[*].type Yes string/EOrderLineType
orderLines[*].SkuCode No string
orderLines[*].name Yes string
orderLines[*].description No string
orderLines[*].quantity Yes string
orderLines[*].unitPriceExclVat Yes* string * = Either one or both unit prices must be specified.
orderLines[*].unitPriceInclVat Yes* string * = Either one or both unit prices must be specified.
orderLines[*].vatPercentage No string
orderLines[*].vatPercentageLabel No string
orderLines[*].discountPercentageLabel No string
orderLines[*].totalLineAmount Yes string
orderLines[*].url No string

Possible success response codes

Code Description Response body
200 Order updated

Possible error response codes

Code Description Response body
400 Invalid request Response object
401 Unauthorized Response object
406 Request was not acceptable Response object
503 Service is (partially) unavailable
504 Gateway timed out
500 Internal server error
PUT
/api/gateway/payment-jobs_/{PaymentJobReference}/order

Request example

<?php

require __DIR__ . '/vendor/autoload.php';

// Create an executor
$execute = new \PaymentGateway\Executor("12345","DE6DA27F-ACFC-463B-91F7-F852FEAC257C","https://gatewayendpoint.example.com");

$ref     = $paymentjob->getReference();

// Update everything from the original order
$postRequest = $paymentjob->getOrder();
$postRequest->setOrderNumber("2019-03-25/1001");
$postRequest->setNote("Updated order");

// Alter identity
$postRequest->getBillingIdentity()->setEmailAddress("sales@example.com");
$postRequest->getBillingIdentity()->setGender(\PaymentGateway\Model\Gender::Female);
$postRequest->getBillingIdentity()->setDateOfBirth(new DateTime('2010-03-17'));

// alter addresses
$postRequest->getBillingAddress()->setTitle("Mr.");
$postRequest->getBillingAddress()->setFirstName("John");
$postRequest->getBillingAddress()->setMiddleName(null);
$postRequest->getBillingAddress()->setLastName("Doe");
$postRequest->getBillingAddress()->setOrganisation("TestCompany");
$postRequest->getBillingAddress()->setAddressLine1("Addressline1");
$postRequest->getBillingAddress()->setAddressLine2("Addressline2");
$postRequest->getBillingAddress()->setZIPCode("XX21 5XX");
$postRequest->getBillingAddress()->setCity("Cambridge");
$postRequest->getBillingAddress()->setPhoneNumber1("+44 9999 000000");
$postRequest->getBillingAddress()->setPhoneNumber1Type(\PaymentGateway\Model\PhoneNumberType::Fixed);
$postRequest->getBillingAddress()->setCountryISO3166Alpha2("GB");

$postRequest->getShippingAddress()->setTitle("Mr.");
$postRequest->getShippingAddress()->setFirstName("John");
$postRequest->getShippingAddress()->setMiddleName("Van");
$postRequest->getShippingAddress()->setLastName("Dijk");
$postRequest->getShippingAddress()->setOrganisation("Sample Business Ltd");
$postRequest->getShippingAddress()->setAddressLine1("Business Centre Road");
$postRequest->getShippingAddress()->setAddressLine2("Unit 7");
$postRequest->getShippingAddress()->setZIPCode("XX12 1XX");
$postRequest->getShippingAddress()->setCity("TestCity");
$postRequest->getShippingAddress()->setPhoneNumber1("+44 9999 123456");
$postRequest->getShippingAddress()->setPhoneNumber1Type(\PaymentGateway\Model\PhoneNumberType::Fixed);
$postRequest->getShippingAddress()->setPhoneNumber2("+44 8888 123456");
$postRequest->getShippingAddress()->setPhoneNumber2Type(\PaymentGateway\Model\PhoneNumberType::Unknown);
$postRequest->getShippingAddress()->setCountryISO3166Alpha2("GB");


// alter orderlines
$postRequest->clearOrderlines();

// Orderlines are set by supplying all order lines of the altered order
$orderline = new \PaymentGateway\Model\Order\OrderLine();
$orderline->setLineNumber("1");
$orderline->setType(\PaymentGateway\Model\Order\OrderLineType::PhysicalItem);
$orderline->setSkuCode("1234567890123");
$orderline->setName("Bike");
$orderline->setQuantity(1);
$orderline->setUnitPriceExclVat(100);
$orderline->setUnitPriceInclVat(121);
$orderline->setVatPercentage(21);
$orderline->setVatPercentageLabel("Vat 21%");
$orderline->setDiscountPercentageLabel("discount 6%");
$orderline->setTotalLineAmount(121);
$postRequest->addOrderLine($orderline);

$orderline = new \PaymentGateway\Model\Order\OrderLine();
$orderline->setLineNumber("2");
$orderline->setType(\PaymentGateway\Model\Order\OrderLineType::PhysicalItem);
$orderline->setSkuCode("1234567890124");
$orderline->setName("Bike 2");
$orderline->setQuantity(2);
$orderline->setUnitPriceExclVat(100);
$orderline->setUnitPriceInclVat(121);
$orderline->setVatPercentage(21);
$orderline->setVatPercentageLabel("Vat 21%");
$orderline->setDiscountPercentageLabel("discount 6%");
$orderline->setTotalLineAmount(242);
$postRequest->addOrderLine($orderline);

$execute->callEndPoint("/api/gateway/payment-jobs/" .$ref . "/order","PUT",$postRequest);

// Analyze result
if ($execute->isSuccess())
{
    $response   = new \PaymentGateway\Api\PaymentJobs\Invoices\PostResponse();
    $result     = $execute->getMappedResponse($response);
    $order      = $result->getData();
    var_dump($order);
}
else
{
    if ($execute->isCurlError())
    {
        var_dump($execute->getCurlError());
        return;
    }
    $result = $execute->getHttpCode() . "[" . $execute->getResponseBody() . "]";
    var_dump($result);
}

Request body

{
    "orderNumber": "2019-03-25/1001",
    "note": "Updated order",
    "createDateTimeUtc": "2019-07-12T12:05:33+0000",
    "billingAddress": {
        "title": "Mr.",
        "firstName": "John",
        "lastName": "Doe",
        "countryIso3166Alpha2": "GB",
        "addressLine1": "Addressline1",
        "addressLine2": "Addressline2",
        "zipCode": "XX21 5XX",
        "city": "Cambridge",
        "phoneNumber1": "+44 9999 000000",
        "phoneNumber1Type": "Fixed",
        "phoneNumber2": "+44 8888 123456",
        "phoneNumber2Type": "Unknown",
        "organisation": "TestCompany"
    },
    "billingIdentity": {
        "emailAddress": "sales@example.com",
        "gender": "Female",
        "dateOfBirth": "2010-03-17T00:00:00+0100"
    },
    "shippingAddress": {
        "title": "Mr.",
        "firstName": "John",
        "middleName": "Van",
        "lastName": "Dijk",
        "countryIso3166Alpha2": "GB",
        "addressLine1": "Business Centre Road",
        "addressLine2": "Unit 7",
        "zipCode": "XX12 1XX",
        "city": "TestCity",
        "phoneNumber1": "+44 9999 123456",
        "phoneNumber1Type": "Fixed",
        "phoneNumber2": "+44 8888 123456",
        "phoneNumber2Type": "Unknown",
        "organisation": "Sample Business Ltd"
    },
    "orderLines": [
        {
            "lineNumber": "1",
            "type": "PhysicalItem",
            "skuCode": "1234567890123",
            "name": "Bike",
            "quantity": "1",
            "unitPriceExclVat": "100",
            "unitPriceInclVat": "121",
            "vatPercentage": "21",
            "vatPercentageLabel": "Vat 21%",
            "discountPercentageLabel": "discount 6%",
            "totalLineAmount": "121"
        },
        {
            "lineNumber": "2",
            "type": "PhysicalItem",
            "skuCode": "1234567890124",
            "name": "Bike 2",
            "quantity": "2",
            "unitPriceExclVat": "100",
            "unitPriceInclVat": "121",
            "vatPercentage": "21",
            "vatPercentageLabel": "Vat 21%",
            "discountPercentageLabel": "discount 6%",
            "totalLineAmount": "242"
        }
    ]
}

Response object

{
    "data": {
        "orderNumber": "2019-03-25/1001",
        "note": "Updated order",
        "createDateTimeUtc": "2019-07-12T12:05:34.0096284Z",
        "billingAddress": {
            "title": "Mr.",
            "firstName": "John",
            "lastName": "Doe",
            "countryIso3166Alpha2": "GB",
            "addressLine1": "Addressline1",
            "addressLine2": "Addressline2",
            "zipCode": "XX21 5XX",
            "city": "Cambridge",
            "phoneNumber1": "+44 9999 000000",
            "phoneNumber1Type": "Fixed",
            "phoneNumber2": "+44 8888 123456",
            "phoneNumber2Type": "Unknown",
            "organisation": "TestCompany"
        },
        "billingIdentity": {
            "emailAddress": "sales@example.com",
            "gender": "Female",
            "dateOfBirth": "2010-03-16T23:00:00+00:00"
        },
        "shippingAddress": {
            "title": "Mr.",
            "firstName": "John",
            "middleName": "Van",
            "lastName": "Dijk",
            "countryIso3166Alpha2": "GB",
            "addressLine1": "Business Centre Road",
            "addressLine2": "Unit 7",
            "zipCode": "XX12 1XX",
            "city": "TestCity",
            "phoneNumber1": "+44 9999 123456",
            "phoneNumber1Type": "Fixed",
            "phoneNumber2": "+44 8888 123456",
            "phoneNumber2Type": "Unknown",
            "organisation": "Sample Business Ltd"
        },
        "orderLines": [
            {
                "lineNumber": "1",
                "type": "PhysicalItem",
                "skuCode": "1234567890123",
                "name": "Bike",
                "quantity": "1",
                "unitPriceExclVat": "100",
                "unitPriceInclVat": "121",
                "vatPercentage": "21",
                "vatPercentageLabel": "Vat 21%",
                "discountPercentageLabel": "discount 6%",
                "totalLineAmount": "121"
            },
            {
                "lineNumber": "2",
                "type": "PhysicalItem",
                "skuCode": "1234567890124",
                "name": "Bike 2",
                "quantity": "2",
                "unitPriceExclVat": "100",
                "unitPriceInclVat": "121",
                "vatPercentage": "21",
                "vatPercentageLabel": "Vat 21%",
                "discountPercentageLabel": "discount 6%",
                "totalLineAmount": "242"
            }
        ]
    }
}

Invoices

Create one invoice

Query parameters

Key Mandatory Type Remark
locale No string/ELocale

Header parameters

Key Mandatory Type Remark
terminalId Yes string
hash Yes string Hexadecimal SHA512 hash of password + body

Request body properties

Property Mandatory Type Remark
invoiceNumber Yes string
dateTimeUtc Yes string/date-time
offline No boolean
billingAddress No Address
billingAddress.title No string
billingAddress.firstName No string
billingAddress.middleName No string
billingAddress.lastName No string
billingAddress.countryIso3166Alpha2 No string/ECountry
billingAddress.addressLine1 No string
billingAddress.addressLine2 No string
billingAddress.zipCode No string
billingAddress.city No string
billingAddress.stateProvince No string
billingAddress.phoneNumber1 No string
billingAddress.phoneNumber1Type No string/EPhoneNumberType
billingAddress.phoneNumber2 No string
billingAddress.phoneNumber2Type No string/EPhoneNumberType
billingAddress.organisation No string
billingAddress.department No string
billingIdentity No Identity
billingIdentity.debtorId No string
billingIdentity.emailAddress No string
billingIdentity.gender No string/EGender
billingIdentity.dateOfBirth No string/date-time
billingIdentity.socialSecurityNumber No string
billingIdentity.chamberOfCommerceNumber No string
billingIdentity.vatNumber No string
shipmentTrackAndTraceInfo No TrackAndTraceInfo
shipmentTrackAndTraceInfo.trackingNumber No string
shipmentTrackAndTraceInfo.trackingUrl No string
shipmentTrackAndTraceInfo.shippingCompany No string
shipmentTrackAndTraceInfo.shippingMethod No string
returnTrackAndTraceInfo No TrackAndTraceInfo
returnTrackAndTraceInfo.trackingNumber No string
returnTrackAndTraceInfo.trackingUrl No string
returnTrackAndTraceInfo.shippingCompany No string
returnTrackAndTraceInfo.shippingMethod No string
totalInvoiceAmount Yes string/decimal
invoiceLines No array[InvoiceLine]
invoiceLines[*].lineNumber Yes string
invoiceLines[*].type Yes string/EOrderLineType
invoiceLines[*].SkuCode No string
invoiceLines[*].name Yes string
invoiceLines[*].description No string
invoiceLines[*].quantity Yes string/decimal
invoiceLines[*].unitPriceExclVat Yes* string/decimal * = Either one or both unit prices must be specified.
invoiceLines[*].unitPriceInclVat Yes* string/decimal * = Either one or both unit prices must be specified.
invoiceLines[*].vatPercentage No string/decimal
invoiceLines[*].vatPercentageLabel No string
invoiceLines[*].discountPercentageLabel No string
invoiceLines[*].totalLineAmount Yes string/decimal
invoiceLines[*].url No string
invoiceLines[*].invoicedQuantity Yes string/decimal
invoiceLines[*].totalInvoicedLineAmount Yes string/decimal
POST
/api/gateway/payment-jobs/{PaymentJobReference}/invoices

Request example

<?php

require __DIR__ . '/vendor/autoload.php';

// Prepare an executor instance
$execute = new \PaymentGateway\Executor("12345","DE6DA27F-ACFC-463B-91F7-F852FEAC257C","https://gatewayendpoint.example.com");

$ref        = $paymentjob->getReference();


// Prepare Invoice in postRequest
$invoice = new \PaymentGateway\Api\Gateway\PaymentJobs\PaymentJobReference\Invoices\PostRequest();
$invoice->setInvoiceNumber("2019-03-18/1001");
$invoice->setDateTimeUtc(new DateTime("2019-04-09"));
$invoice->setTotalInvoiceAmount(120.00);
$invoice->setBillingIdentity(new \PaymentGateway\Model\Identity());
$invoice->setBillingAddress(new \PaymentGateway\Model\Address());
$invoice->setReturnTrackAndTraceInfo(new \PaymentGateway\Model\PaymentJob\Invoice\TrackAndTraceInfo());
$invoice->setShipmentTrackAndTraceInfo(new \PaymentGateway\Model\PaymentJob\Invoice\TrackAndTraceInfo());

// Prepare identity
$invoice->getBillingIdentity()->setEmailAddress("martien.Doe@example.com");
$invoice->getBillingIdentity()->setGender(\PaymentGateway\Model\Gender::Male);

// Prepare addresses
$invoice->getBillingAddress()->setTitle("Mr.");
$invoice->getBillingAddress()->setFirstName("John");
$invoice->getBillingAddress()->setMiddleName("Van");
$invoice->getBillingAddress()->setLastName("Dijk");
$invoice->getBillingAddress()->setOrganisation("Sample Business Ltd");
$invoice->getBillingAddress()->setAddressLine1("Business Centre Road");
$invoice->getBillingAddress()->setAddressLine2("Unit 7");
$invoice->getBillingAddress()->setZIPCode("XX12 1XX");
$invoice->getBillingAddress()->setCity("TestCity");
$invoice->getBillingAddress()->setPhoneNumber1("+44 9999 123456");
$invoice->getBillingAddress()->setPhoneNumber1Type(\PaymentGateway\Model\PhoneNumberType::Fixed);
$invoice->getBillingAddress()->setPhoneNumber2("+44 8888 123456");
$invoice->getBillingAddress()->setPhoneNumber2Type(\PaymentGateway\Model\PhoneNumberType::Unknown);
$invoice->getBillingAddress()->setCountryISO3166Alpha2("GB");

$invoice->getReturnTrackAndTraceInfo()->setShippingCompany("DHL");
$invoice->getReturnTrackAndTraceInfo()->setShippingMethod("DHL Fastdelivery");
$invoice->getReturnTrackAndTraceInfo()->setTrackingNumber("1234556666");
$invoice->getReturnTrackAndTraceInfo()->setTrackingUrl("https://dhl.com/tracking/1234556666");

$invoice->getShipmentTrackAndTraceInfo()->setShippingCompany("PostNL");
$invoice->getShipmentTrackAndTraceInfo()->setShippingMethod("Aangetekend");
$invoice->getShipmentTrackAndTraceInfo()->setTrackingNumber("123456");
$invoice->getShipmentTrackAndTraceInfo()->setTrackingUrl("https://post.nl/tracking/123456");

// Add invoice line
$invoiceline = new \PaymentGateway\Model\PaymentJob\Invoice\InvoiceLine();
$invoiceline->setLineNumber("1");
$invoiceline->setType(\PaymentGateway\Model\Order\OrderLineType::PhysicalItem);
$invoiceline->setSkuCode("1234567890123");
$invoiceline->setName("Bike");
$invoiceline->setQuantity(1);
$invoiceline->setUnitPriceExclVat(100);
$invoiceline->setUnitPriceInclVat(121);
$invoiceline->setVatPercentage(21);
$invoiceline->setVatPercentageLabel("Vat 21%");
$invoiceline->setDiscountPercentageLabel("discount 6%");
$invoiceline->setTotalLineAmount(121);
$invoiceline->setTotalInvoicedLineAmount(121);
$invoiceline->setInvoicedQuantity(1);
$invoice->addInvoiceLine($invoiceline);

$execute->callEndPoint("/api/gateway/payment-jobs/" . $ref . "/invoices","POST",$invoice);

if ($execute->isSuccess())
{
    $response   = new \PaymentGateway\Api\PaymentJobs\Invoices\PostResponse();
    $result     = $execute->getMappedResponse($response);
    $available  = $result->getData();
    var_dump($available);
    echo "<br/>";
}
else
{
    if ($execute->isCurlError())
    {
        var_dump($execute->getCurlError());
        return;
    }
    $result = $execute->getHttpCode() . "[" . $execute->getResponseBody() . "]";
    var_dump($result);
    echo "<br/>";
}

Request body

{
    "invoiceNumber": "2019-03-18/1001",
    "dateTimeUtc": "2019-04-09T00:00:00+0200",
    "billingAddress": {
        "title": "Mr.",
        "firstName": "John",
        "middleName": "Van",
        "lastName": "Dijk",
        "countryIso3166Alpha2": "GB",
        "addressLine1": "Business Centre Road",
        "addressLine2": "Unit 7",
        "zipCode": "XX12 1XX",
        "city": "TestCity",
        "phoneNumber1": "+44 9999 123456",
        "phoneNumber1Type": "Fixed",
        "phoneNumber2": "+44 8888 123456",
        "phoneNumber2Type": "Unknown",
        "organisation": "Sample Business Ltd"
    },
    "billingIdentity": {
        "emailAddress": "martien.Doe@example.com",
        "gender": "Male"
    },
    "shipmentTrackAndTraceInfo": {
        "trackingNumber": "123456",
        "trackingUrl": "https://post.nl/tracking/123456",
        "shippingCompany": "PostNL",
        "shippingMethod": "Aangetekend"
    },
    "returnTrackAndTraceInfo": {
        "trackingNumber": "1234556666",
        "trackingUrl": "https://dhl.com/tracking/1234556666",
        "shippingCompany": "DHL",
        "shippingMethod": "DHL Fastdelivery"
    },
    "totalInvoiceAmount": "120",
    "invoiceLines": [
        {
            "invoicedQuantity": "1",
            "totalInvoicedLineAmount": "121",
            "lineNumber": "1",
            "type": "PhysicalItem",
            "skuCode": "1234567890123",
            "name": "Bike",
            "quantity": "1",
            "unitPriceExclVat": "100",
            "unitPriceInclVat": "121",
            "vatPercentage": "21",
            "vatPercentageLabel": "Vat 21%",
            "discountPercentageLabel": "discount 6%",
            "totalLineAmount": "121"
        }
    ]
}```

**Possible success response codes**

| Code | Description     | Response body   |
| ---- | --------------- | --------------- |
| 501  | Not implemented | Response object |

**Possible error response codes**

| Code | Description                        | Response body   |
| ---- | ---------------------------------- | --------------- |
| 400  | Invalid request                    | Response object |
| 401  | Unauthorized                       | Response object |
| 404  | Payment job not found              | Response object |
| 406  | Request was not acceptable         | Response object |
| 503  | Service is (partially) unavailable |                 |
| 504  | Gateway timed out                  |                 |
| 500  | Internal server error              |                 |

#### Response object

​```json
{
    "data": {
        "reference": "190724017179869188",
        "invoiceNumber": "2019-03-18/1001",
        "dateTimeUtc": "2019-04-08T22:00:00+00:00",
        "offline": false,
        "billingAddress": {
            "title": "Mr.",
            "firstName": "John",
            "middleName": "Van",
            "lastName": "Dijk",
            "countryIso3166Alpha2": "GB",
            "addressLine1": "Business Centre Road",
            "addressLine2": "Unit 7",
            "zipCode": "XX12 1XX",
            "city": "TestCity",
            "phoneNumber1": "+44 9999 123456",
            "phoneNumber1Type": "Fixed",
            "phoneNumber2": "+44 8888 123456",
            "phoneNumber2Type": "Unknown",
            "organisation": "Sample Business Ltd"
        },
        "billingIdentity": {
            "emailAddress": "martien.Doe@example.com",
            "gender": "Male"
        },
        "shipmentTrackAndTraceInfo": {
            "trackingNumber": "123456",
            "trackingUrl": "https://post.nl/tracking/123456",
            "shippingCompany": "PostNL",
            "shippingMethod": "Aangetekend"
        },
        "returnTrackAndTraceInfo": {
            "trackingNumber": "1234556666",
            "trackingUrl": "https://dhl.com/tracking/1234556666",
            "shippingCompany": "DHL",
            "shippingMethod": "DHL Fastdelivery"
        },
        "totalInvoiceAmount": "120",
        "invoiceLines": [
            {
                "invoicedQuantity": "1",
                "totalInvoicedLineAmount": "121",
                "lineNumber": "1",
                "type": "PhysicalItem",
                "skuCode": "1234567890123",
                "name": "Bike",
                "quantity": "1",
                "unitPriceExclVat": "100",
                "unitPriceInclVat": "121",
                "vatPercentage": "21",
                "vatPercentageLabel": "Vat 21%",
                "discountPercentageLabel": "discount 6%",
                "totalLineAmount": "121"
            }
        ]
    }
}

Refunds

Create one refund

Query parameters

Key Mandatory Type Remark
locale No string/ELocale

Header parameters

Key Mandatory Type Remark
terminalId Yes string
hash Yes string Hexadecimal SHA512 hash of password + body

Request body properties

Property Mandatory Type Remark
amountToRefund No string/decimal
creditNumber Yes string
creditNote No string
parameters No Parameters

Possible success response codes

Code Description Response body
201 Refund created Response object

Possible error response codes

Code Description Response body
400 Invalid request Response object
401 Unauthorized Response object
404 Payment job or payment not found Response object
406 Request was not acceptable Response object
503 Service is (partially) unavailable
504 Gateway timed out
500 Internal server error
POST
/api/gateway/payment-jobs/{PaymentJobReference}/payments/{PaymentReference}/refunds

Request example

<?php

require __DIR__ . '/vendor/autoload.php';

// Prepare executor
$execute = new \PaymentGateway\Executor("12345","DE6DA27F-ACFC-463B-91F7-F852FEAC257C","https://gatewayendpoint.example.com");

// Use data from previous paymentjob it's payment
$paymentjobRef = $paymentjob->getReference();
$paymentRef    = $paymentjob->getPayments()[0]->getReference();

// Create post for refund
$refund = new \PaymentGateway\Api\PaymentJobs\Payments\Refund\PostRequest();
$refund->setAmountToRefund(0.85);
$refund->setCreditNumber("1234");
$refund->setCreditNote("Credit note");

$execute->callEndPoint("/api/gateway/payment-jobs/" . $paymentjobRef . "/payments/" . $paymentRef . "/refunds?locale=NL_nl","POST",$refund);
if ($execute->isSuccess())
{
    $result     = $execute->getMappedResponse(new \PaymentGateway\Api\PaymentJobs\Payments\Refund\PostResponse());
    $available  = $result->getData();
    var_dump($available);
}
else
{
    if ($execute->isCurlError())
    {
        var_dump($execute->getCurlError());
        return;
    }
    if ( ($execute->getResponseBody() !== NULL) && (strcasecmp($execute->getResponseContentType(),"application/json") == 0))
    {
        $result = $execute->getMappedResponse(new \PaymentGateway\Api\PaymentJobs\Payments\Refund\PostResponse());
    }
    else
    {
        $result = $execute->getHttpCode() . "[" . $execute->getResponseBody() . "]";
    }
    var_dump($result);
}

Request body

{
  "creditNumber": "1234",
  "creditNote": "Credit note",
  "amountToRefund": "0.85"
}

Response object

{
    "data": {
        "reference": "190723017339252744",
        "createDateTimeUtc": "2019-07-12T12:14:47.8957615Z",
        "creditNumber": "1234",
        "creditNote": "Credit note",
        "status": "Completed",
        "amountToRefund": "0.85",
        "steps": [
            {
                "reference": "190723117330864144",
                "createDateTimeUtc": "2019-07-12T12:14:47.8958492Z",
                "action": "Start",
                "status": "Completed"
            }
        ]
    }
}

Captures

Create one capture

Query parameters

Key Mandatory Type Remark
locale No string/ELocale

Header parameters

Key Mandatory Type Remark
terminalId Yes string
hash Yes string Hexadecimal SHA512 hash of password + body

Request body properties

Property Mandatory Type Remark
amountToCapture No string/decimal If omitted the entire remaining amount is captured.
isFinalCapture No boolean If set to true no future captures are possible on the payment. Implicitly set to true in case the entire amount is captured.
parameters No Parameters

Possible success response codes

Code Description Response body
201 Capture created Response object

Possible error response codes

Code Description Response body
400 Invalid request Response object
401 Unauthorized Response object
404 Payment job or payment not found Response object
406 Request was not acceptable Response object
503 Service is (partially) unavailable
504 Gateway timed out
500 Internal server error
POST
/api/gateway/payment-jobs/{PaymentJobReference}/payments/{PaymentReference}/captures

Request example

<?php

require __DIR__ . '/vendor/autoload.php';

// Prepare executor
$execute = new \PaymentGateway\Executor("12345","DE6DA27F-ACFC-463B-91F7-F852FEAC257C","https://gatewayendpoint.example.com");


$paymentjobRef = $paymentjob->getReference();
$paymentRef    = $paymentjob->getPayments()[0]->getReference();

// Create post for capture
$capture = new \PaymentGateway\Api\PaymentJobs\Payments\Capture\PostRequest();
$capture->setAmountToCapture(0.85);

$execute->callEndPoint("/api/gateway/payment-jobs/" . $paymentjobRef . "/payments/" . $paymentRef . "/captures?locale=NL_nl","POST",$capture);
if ($execute->isSuccess())
{
    $result     = $execute->getMappedResponse(new \PaymentGateway\Api\PaymentJobs\Payments\Capture\PostResponse());
    $available  = $result->getData();
    var_dump($available);
}
else
{
    if ($execute->isCurlError())
    {
        var_dump($execute->getCurlError());
        return;
    }
    if ( ($execute->getResponseBody() !== NULL) && (strcasecmp($execute->getResponseContentType(),"application/json") == 0))
    {
        $result = $execute->getMappedResponse(new \PaymentGateway\Api\PaymentJobs\Payments\Refund\PostResponse());
    }
    else
    {
        $result = $execute->getHttpCode() . "[" . $execute->getResponseBody() . "]";
    }
    var_dump($result);
}

Request body

{
    "amountToCollect": "121"
}

Response object

{
    "data": {
        "reference": "190723517188388876",
        "createDateTimeUtc": "2019-07-12T12:24:29.4719726Z",
        "status": "Completed",
        "amountToCapture": "121",
        "isFinalCapture": true
    }
}

Creditcard Tokenisation

The paymentgateway has the ability to generate creditcard tokens. As an implementer you should store all returned data for future reference. The "truncatedCardNumber" is a value to be presented to the enduser to identify which card represents the token.

To initiate a payment, using the generated token, you only need to supply the token and expiry dates.

The tokenisation request needs the securitycode of the credit card to verify ownership, technically a ZeroAuth is performed to assure the card is valid.

Request tokenization

Query parameters

Key Mandatory Type Remark
locale No string/ELocale

Header parameters

Key Mandatory Type Remark
terminalId Yes string
hash Yes string Hexadecimal SHA512 hash of password + body

Request body properties

Property Mandatory Type Remark
cardNumber Yes string Valid creditcard number
cardExpiryYear Yes string Card expiry (last 2 digits of year)
cardExpiryMonth yes string Card expriy month (2 digits, range 01-12)
cardCvc yes string Card security code (3 or 4 digits depending on cardtype)

Possible success response codes

Code Description Response body
200 Token created Response object

On success the response object contains a CreditcardTokenizationResponse in the data section.

Possible error response codes

Code Description Response body
400 Invalid request Response object
401 Unauthorized Response object
500 Internal server error
503 Service is (partially) unavailable
504 Gateway timed out
POST
/api/gateway/creditcard-tokenization

Request example

<?php

echo "Starting\n";

require __DIR__ . '/vendor/autoload.php';

// Prepare an executor instance
$execute = new \PaymentGateway\Executor("12345","DE6DA27F-ACFC-463B-91F7-F852FEAC257C","https://gatewayendpoint.example.com");

// Prepare post request
$postRequest = new \PaymentGateway\Api\Gateway\CreditcardTokenization\PostRequest();
$postRequest->setCardNumber('4000000000000002');
$postRequest->setCardExpiryYear("20");
$postRequest->setCardExpiryMonth("12");
$postRequest->setCardCvc("123");

// Excecute
$execute->callEndPoint("/api/gateway/creditcard-tokenization?locale=en_GB","POST",$postRequest);

// Analyze result
if ($execute->isSuccess())
{
    $result = new \PaymentGateway\Api\Gateway\CreditcardTokenization\PostResponse();
    $execute->getMappedResponse($result);
    $available  = $result->getData();

    var_dump($available);
    Var_dump($result->getErrorReport());
}
else
{
    if ($execute->isCurlError())
    {
        var_dump($execute->getCurlError());
        return;
    }
    $result = $execute->getHttpCode() . "[" . $execute->getResponseBody() . "]";
    var_dump($result);
}
echo "Complete\n";

Request body

{
	CardNumber: "4000000000000002",
	CardExpiryYear: "21",
	CardExpiryMonth: "10",
	CardCvc: "123",
}

Response object

{
	"data": {
        "token": "1000000000030419",
        "cardExpiryMonth": "10",
        "cardExpiryYear": "21",
        "truncatedCardNumber": "400000****0002"
	}
}

Account Update

The account update call has the function to update your creditcard base. As this is a batch process it consists of a request supplying all the creditcards you want to update. And after a successfull post you retrieve the processed values using the request id.

Live processing can take up from a few hours to a couple of days depending on timing of the scheme processing the requests.

Integration testing

If you are programming in the integration environment you can test the integration using the information below. Expect results to appear in a couple of minutes.

The ExpiryDate in the request will dictate the kind of response given by this test file conversion code.

Visa testcards: 4000000000000002 and 4462030000000000

ExpiryDate Expected response
0100 skips this record in the results
0101 “A”. Account number change message (no change to expiry)
0201 “C”. Closed account advice
0301 “E”. Expiry date change message
0401 “N”. Non-participating BIN
0501 “P”. Participating BIN, no match
0601 “Q”. Contact cardholder advice
0701 “V”. Match made, account number and expiration date unchanged
All others “A”. Account number change message (and new expiry)

If the response returns a new card number we will return: 4444333322221111

Mastercard testcards: 5555555555554444 and 5597507644910558

ExpiryDate Expected response
0102 “CONTAC”. match made; account closed.
0202 “EXPIRY”. match made; expiry date changed
0302 “VALID” “V”. No updates found, but account is valid
0402 “UNKNWN” “P”. BIN is participating, no match
0502 “UNKNWN” “N”. Non-participating BIN
0602 “000101”. non-numeric account number
0702 “000103”. invalid expiration date
0802 “000104”. merchant not registered
0902 “000122”. unregistered sub-merchant
All others “UPDATE”. match made; update data provided

If the response returns a new card number we will return: 5506900140100305

Request account updates

Query parameters

Key Mandatory Type Remark
locale No string/ELocale

Header parameters

Key Mandatory Type Remark
terminalId Yes string
hash Yes string Hexadecimal SHA512 hash of password + body

Request body properties

Property Mandatory Type Remark
merchantId No string/decimal Merchant Id (Acquirer MID) to send in requests.
details No array List of accounts to get updates for.
details[*].Cardnumber yes string The full Primary Account Number (PAN) on the card.
details[*].ExpiryDate yes string The payment card’s expiry date and month. Format: mmyy. Example: 1225.

Possible success response codes

Code Description Response body
200 Request created Response object

On success the response object contains a AccountUpdateResult in the data section.

Possible error response codes

Code Description Response body
400 Invalid request Response object
401 Unauthorized Response object
500 Internal server error
503 Service is (partially) unavailable
504 Gateway timed out
POST
/api/account-updater/request-account-update

Request example

<?php

echo "Starting\n";

require __DIR__ . '/vendor/autoload.php';

// Prepare an executor instance
$execute = new \PaymentGateway\Executor("12345","DE6DA27F-ACFC-463B-91F7-F852FEAC257C","https://gatewayendpoint.example.com");

// Prepare post request for account updater
$postRequest = new \PaymentGateway\Api\AccountUpdater\RequestAccountUpdate\PostRequest();
$postRequest->setMerchantId("2263");

// Prepare post request detail(s)
$postRequestDetail = new \PaymentGateway\Model\AccountUpdater\RequestAccountUpdateRequestDetail();
$postRequestDetail->setCardNumber("4000000000000002");
$postRequestDetail->setExpiryDate("0102");

$postRequest->addDetail($postRequestDetail);

// Excecute
$execute->callEndPoint("/api/account-updater/request-account-update","POST",$postRequest);

// Analyze result
if ($execute->isSuccess())
{
    $result = new \PaymentGateway\Api\AccountUpdater\RequestAccountUpdate\PostResponse();
    $execute->getMappedResponse($result);
    $available  = $result->getData();

    var_dump($available);
    Var_dump($result->getErrorReport());
}
else
{
    if ($execute->isCurlError())
    {
        var_dump($execute->getCurlError());
        return;
    }
    $result = $execute->getHttpCode() . "[" . $execute->getResponseBody() . "]";
    var_dump($result);
}
echo "Complete\n";

Request body

{
    "merchantId": "2263",
    "details": [
        {
            "cardNumber": "4444333322221111",
            "expiryDate": "0118"
        },
        {
            "cardNumber": "5555444433332222",
            "expiryDate": "0119"
        },
        {
            "cardNumber": "5555444433331111",
            "expiryDate": "0119"
        }
    ]
}

Response object

{
	"data": {
		"requestId": "6fbc91f55d7e401ea89e91dd5fe52af7",
		"merchantId": "2263",
		"results": null,
		"status": 1
	}
}

Retrieve account updates

Query parameters

Key Mandatory Type Remark
locale No string/ELocale

Header parameters

Key Mandatory Type Remark
terminalId Yes string
hash Yes string Hexadecimal SHA512 hash of password + body

Request body properties

Property Mandatory Type Remark
requestId yes string(32) Unique ID returned in the response to the account update request.

Possible success response codes

Code Description Response body
200 Request created Response object

On success the response object contains a AccountUpdateResult in the data section.

Possible error response codes

Code Description Response body
400 Invalid request Response object
401 Unauthorized Response object
500 Internal server error
503 Service is (partially) unavailable
504 Gateway timed out
POST
/api/account-updater/retrieve-account-update

Request example

<?php

echo "Starting\n";

require __DIR__ . '/vendor/autoload.php';

// Prepare an executor instance
$execute = new \PaymentGateway\Executor("12345","DE6DA27F-ACFC-463B-91F7-F852FEAC257C","https://gatewayendpoint.example.com");

// Prepare request to retrieve account updater status
$postRequest = new \PaymentGateway\Api\AccountUpdater\RetrieveAccountUpdate\PostRequest();
$postRequest->setRequestId("6fbc91f55d7e401ea89e91dd5fe52af7");

// Excecute
$execute->callEndPoint("/api/account-updater/retrieve-account-update","POST",$postRequest);

// Analyze result
if ($execute->isSuccess())
{
    echo "<br>json->" . ($execute->getResponseBody()) . "<br>";

    $result = new \PaymentGateway\Api\AccountUpdater\RetrieveAccountUpdate\PostResponse();
    $execute->getMappedResponse($result);
    $available  = $result->getData();

    var_dump($available);
    Var_dump($result->getErrorReport());
}
else
{
    if ($execute->isCurlError())
    {
        var_dump($execute->getCurlError());
        return;
    }
    $result = $execute->getHttpCode() . "[" . $execute->getResponseBody() . "]";
    var_dump($result);
}

echo "Complete";

Request body

{
	"requestId": "6fbc91f55d7e401ea89e91dd5fe52af7"
}

Response object

{
	"data": {
		"requestId": "6fbc91f55d7e401ea89e91dd5fe52af7",
		"merchantId": "5912345",
		"results": [{
				"oldCardNumber": "4444333322221111",
				"oldExpiryDate": "0118",
				"newCardNumber": "4444333332225555",
				"newExpiryDate": "0221",
				"vauRawResponse": {
					"responseCode": "A"
				},
				"status": 2
			}, {
				"oldCardNumber": "5555444433332222",
				"oldExpiryDate": "0119",
				"newCardNumber": "5555444433331000",
				"newExpiryDate": "0122",
				"abuRawResponse": {
					"reasonIdentifier": "Update",
					"responseIndicator": null
				},
				"status": 2
			}, {
				"oldCardNumber": "5555444433331111",
				"oldExpiryDate": "0119",
				"status": 3
			}
		]
	}
}

Portal API Overview

The main responsibility of the Portal API is to disclose all necessary information to the frontend portal. It contains all kind of endpoints to create, retrieve and update this information.

Authorization

Almost every request to the Portal Api needs to have a authorization header:

  • Bearer [accesstoken]

Endpoint

DNS of Portal API and Payment Gateway API can be different.

URL
/api/portal*

Dynamic enumerations

Get a list of countries

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

none

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Request body properties

none

Possible response codes

Code Cause Body
200 Currency list retrieved Response object
400 Parsing or validating failed Response object
401 The user is not authorized
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
data array[Country] The data to return.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
GET
/api/portal/enumerations/countries

Request example


Request body


Response object

{
	"data": [
        {
            "alpha2Code": "AF",
            "numericCode": 4,
            "fullName": "Afghanistan"
        },
        {
            "alpha2Code": "AL",
            "numericCode": 8,
            "fullName": "Albania"
        }
    ],
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Get a list of currencies

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

none

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Request body properties

none

Possible response codes

Code Cause Body
200 Currency list retrieved Response object
400 Parsing or validating failed Response object
401 The user is not authorized
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
data array[Currency] The data to return.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
GET
/api/portal/enumerations/currencies

Request example


Request body


Response object

{
	"data": [
        {
		  "alpha3Code": "AUD",
		  "numericCode": 36,
		  "symbol": "$",
		  "numberOfDecimalPlaces": 2
		},
		{
		  "alpha3Code": "CAD",
		  "numericCode": 124,
		  "symbol": "$",
		  "numberOfDecimalPlaces": 2
		}
    ],
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Get a list of payment methods

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

none

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Request body properties

none

Possible response codes

Code Cause Body
200 Payment method list retrieved Response object
400 Parsing or validating failed Response object
401 The user is not authorized
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
data array[[string] The data to return.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
GET
/api/portal/enumerations/payment-methods

Request example


Request body


Response object

{
	"data": [
        "Ideal",
		"PayPal",
		"Creditcard",
		"Bancontact",
		"SepaBanktransfer",
		"KlarnaPayLater",
		"KlarnaSliceIt",
		"KlarnaPayNow",
		"AfterPay",
		"DirectDebit"
    ],
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Get a list of payment status

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

none

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Request body properties

none

Possible response codes

Code Cause Body
200 Payment status list retrieved Response object
400 Parsing or validating failed Response object
401 The user is not authorized
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
data array[[string] The data to return.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
GET
/api/portal/enumerations/payment-statuses

Request example


Request body


Response object

{
	"data": [
        "Pending",
		"Reserved",
		"Commissioned",
		"Paid",
		"Cancelled",
		"Failed",
		"Rejected",
		"Expired",
		"Blocked",
		"Declined"
    ],
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Get a list of order line types

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

none

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Request body properties

none

Possible response codes

Code Cause Body
200 Order line type list retrieved Response object
400 Parsing or validating failed Response object
401 The user is not authorized
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
data array[[string] The data to return.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
GET
/api/portal/enumerations/order-line-types

Request example


Request body


Response object

{
	"data": [
        "PhysicalItem",
		"DigitalItem",
		"ShippingCost",
		"PaymentCost",
		"Discount",
		"GiftCard",
		"ShopCredit"
    ],
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

IdentityServer

Get login redirect url

If the user is not yet logged in, he/she needs to be redirected to the central login page. The url for this login page can be obtained with a call to the login endpoint.

Header parameters

Key Type Mandatory

Query parameters

Key Type Mandatory
client_id The client id (which is the application in oauth2 terms), for example "PortalHybrid". yes
state The state to return to after login. This is the part after the domain, for example "/paymentjob/xxx". yes
redirect_url The redirect url to return to after login. This url must be whitelisted on the identity server instance. yes
locale string/ELocale no

Possible response codes

Code Cause Body
200 OK Response object
400 Parsing or validating failed Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
data Link The login url to redirect to.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
GET
/api/portal/identity-server/login/

Request example


Response object

{
    "data": {
        "url": "https://portal.paycheckout.com",
        "type": "text/html"
    },
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Create access token

After the user has logged in he/she will be redirected back to the supplied redirect_url with an authorization code parameter. This is called an authorization grant and can be used to obtain an access token with a call to the access endpoint. This is also the same endpoint that can be used to obtain a new access token with the use of a refresh token that is supplied alongside earlier access tokens.

Header parameters

Key Type Mandatory

Query parameters

Key Type Mandatory

Request body properties

Key Mandatory Type Remark
clientId yes string The client id (which is an application on oauth2 terms), for example "PortalHybrid".
GrantType yes string/EGrantType Type type of grant used to create an access token.
Grant yes string The grant used to create an access token.
RedirectUrl no* string The redirect url. Mandatory if GrantType is set to authorizationCode.

Possible response codes

Code Cause Body
201 Created Response object
400 Parsing or validating failed Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
data Access The access object.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.

REMARK: UserInfo is only returned in case of grantType "authorizationCode". When grantType "refreshtoken" is used, no UserInfo will be returned.

POST
/api/portal/identity-server/access/

Request example

{
    "clientId": "PortalHybrid",
    "grantType": "authorizationCode",
    "grant": "the-authorization-code-grant-goes-here",
    "redirectUrl": "https://portal.paycheckout.com"
}
{
    "clientId": "PortalHybrid",
    "grantType": "refreshToken",
    "grant": "the-refresh-token-grant-goes-here"
}

Response object

{
    "data": {
        "credentials": {
            "accessToken": "5dad4fed4112a8a3dc9bc6be0651f1f64936384d8b52bc4ea7bf3c9140633b0d",
            "validUntilUtc": "2019-05-02T11:14:17.0263281Z",
            "refreshToken": "fe5de86c6eadab9bf5cf8991338986f869eba34c0106f413ca1e805e77a1cd78",
            "idToken": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjBFMjEzN0Y5RTdEMDIwMUFCQUY0Mj",
        },
        "userInfo": {
			"userId": "34fghe34-e0c0-43dc-a5b7-b54433e14c4d",
			"email": "example@domain.com",
			"firstName": "John",
			"lastName": "Doe"
		}
    }
}

Get logout redirect url

To explicitly log the user out he/she needs to be redirected to a centralized logout page.The url for this logout page can be obtained with a call to the logout endpoint.

Header parameters

Key Type Mandatory

Query parameters

Key Type Mandatory
id_token The id_token obtained during login and access token creation. yes
state The state to return to after logout. This is the part after the domain, for example "/paymentjob/xxx". yes
redirect_url The redirect url to return to after logout. This url must be whitelisted on the identity server instance. yes
locale string/ELocale no

Possible response codes

Code Cause Body
200 OK Response object
400 Parsing or validating failed Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
data Link The link to redirect to.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
GET
/api/portal/identity-server/logout/

Request example


Response object

{
    "data": {
        "url": "https://portal.paycheckout.com",
        "type": "text/html"
    },
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Users

Create new user

Create a new user for a businness & merchant combi, with one or more roles. The possible roles to assign are defined by permissions of the logged in user.

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Users.Create Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Request body properties

Key Mandatory Type Remark
email yes string The email of the user.
password yes string The password for the user.
firstName yes string The first name for the user.
lastName yes string The last name for the user.
phoneNumber no string The phone number for the user.
roles yes array[string] The roles to assign to the user.

Possible response codes

Code Cause Body
201 user created Response object
400 Parsing or validating failed Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
data UserInfo The data to return.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
POST
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/users

Request example


Request body

{
    "email": "example@domain.com",
    "password": "Passw0rd!",
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "01632 960761",
    "roles": [
    	"Sales"
    ]
}

Response object

{
	"data": {
		"userId": "34fghe34-e0c0-43dc-a5b7-b54433e14c4d",
		"email": "example@domain.com",
		"firstName": "John",
		"lastName": "Doe",
		"isDeleted": false,
		"roles": [
			"Sales"
    	]
	},
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Retrieve users

Retrieve a list of users for to the requested business and merchant. Only users within roles that can be assigned by the requester (the logged in user) will be returned.

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Users.Read Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Possible response codes

Code Cause Body
200 One or more users found Response object
400 Parsing or validating failed Response object
404 No users found Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
data UserInfo The data to return.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
GET
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/users

Request example


Response object

{
    "data": [
        {
			"userId": "34fghe34-e0c0-43dc-a5b7-b54433e14c4d",
			"email": "example@domain.com",
			"firstName": "John",
			"lastName": "Doe",
			"isDeleted": false,
			"roles": [
				"Sales"
			]
		}
    ],
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Update user

Update a user for a businness & merchant combi, with one or more roles. The possible roles to assign are defined by permissions of the logged in user.

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Users.Update Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Request body properties

Key Mandatory Type Remark
roles no array[string] The roles to assign to the user.

Possible response codes

Code Cause Body
200 User updated Response object
400 Parsing or validating failed Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
data UserInfo The data to return.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
PUT
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/users/{UserId}

Request example


Request body

{
    "roles": [
    	"Owner"
    ]
}

Response object

{
	"data": {
		"userId": "34fghe34-e0c0-43dc-a5b7-b54433e14c4d",
		"email": "example@domain.com",
		"firstName": "John",
		"lastName": "Doe",
		"isDeleted": false,
		"roles": [
			"Owner"
    	]
	},
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Delete user

Mark a user as deleted.

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Users.Delete Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Possible response codes

Code Cause Body
200 User deleted
400 Parsing or validating failed Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
DELETE
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/users/{UserId}

Request example


Response object

{
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Retrieve manageable roles

Retrieve a list of roles which the logged-in user can assign to or revoke from other users on the requested business and merchant.

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Users.Read Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Possible response codes

Code Cause Body
200 Manageable roles returned Response object
400 Parsing or validating failed Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
data array[string] The data to return.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
GET
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/roles

Request example


Response object

{
    "data": [
        "Owner",
        "Sales",
        "Legal"
    ],
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Traces

Retrieve one trace

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Traces.Read Or
Portal.Traces.Read.Advanced Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Possible response codes

Code Cause Body
200 Requested trace found Response object
400 Parsing or validating failed Response object
401 Unauthorized Response object
404 Requested trace not found Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
data Trace The data to return.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
GET
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}/traces/{TraceReference}

Request example


Response object

{
    "data": {
        "reference": "string/long",
        "traceSequences": [
            {
                "sequence": "string/long",
                "timestampUtc": "string/date-time",
                "machineName": "string",
                "state": "string",                
                "traceString": "string",
                "comment": "string",
                "fromEndpoint": "string",
                "toEndpoint": "string",
                "success": "bool",
                "isPrivate": "bool",
                "diagnostic": "string",
                "ipAddress": "string"
            }
        ],		
    },
	"errorReport": {
        "language": "nl_NL",
        "isFatalError": true,
        "errors": [
            {
                "code": "ErrorCode",
                "message": "Error message default",
                "translatedMessage": "Foutmelding standaard",
                "parameters": [
                    "default"
                ]
            }
        ],
        "warnings": [
            {
                "code": "WarningCode_1",
                "message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
                "parameters": [
                    "default"
                ]
            }
        ]
    },
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Retrieve traces

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Traces.Read Or
Portal.Traces.Read.Advanced Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no
diagnostic string (no controlChar_Tag)
ip string (no controlChar_Tag)
olderthan string/date-time (ISO 8601)
newerthan string/date-time (ISO 8601)
pagenumber integer
pagesize integer Default and maximum 1000

Possible response codes

Code Cause Body
200 One or more traces are found Response object
400 Parsing or validating failed Response object
404 No traces are found Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
data array[Trace] The data to return.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
GET
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}/traces

Request example


Response object

{
    "data": [
        {
            "reference": "string/long",
            "traceSequences": [
                {
                    "sequence": "string/long",
                    "timestampUtc": "string/date-time",
                    "machineName": "string",
                    "state": "string",
                    "traceString": "string",
                    "fromEndpoint": "string",
                    "toEndpoint": "string",
                    "success": "bool",
                    "ipAddress": "string"
                }
            ]
        }
    ],
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

PaymentJobs

Retrieve one payment job

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.PaymentJobs.Read Or
Portal.PaymentJobs.Read.Advanced Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Possible response codes

Code Cause Body
200 Requested payment job found Response object
400 Parsing or validating failed Response object
401 Unauthorized Response object
404 Requested payment job not found Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
data PaymentJob The data to return.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
GET
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}/paymentjobs/{PaymentJobReference}

Request example


Response object

{
    "data": {
        "reference": "190321121911044096",
        "createDateTimeUtc": "2019-03-12T13:03:21.888Z",
        "type": "Payment",
        "traceReference": "190320117314091076",
        "terminalId": "12345",
        "domain": "cashflows.com",
        "terminalMetaData": "metadata",
        "locale": "nl_NL",
        "order": {
        	"orderNumber": "123123",
            "note": "Please draw something cool on the box",
            "billingAddress": {
                "title": "Dhr.",
                "firstName": "Henk",
                "middleName": "van",
                "lastName": "Loo",
                "countryIso3166Alpha2": "NL",
                "addressLine1": "Dorpsstraat 12",
                "addressLine2": "kamer 1",
                "zipCode": "1234AB",
                "city": "Amsterdam",
                "stateProvince": "Noord-Holland",
                "phoneNumber1": "0612345678",
                "phoneNumber1Type": "Mobile",
                "phoneNumber2": "+31687654321",
                "phoneNumber2Type": "Mobile",
                "organisation": "CashFlows",
                "department": "Venray Office"
            },
            "billingIdentity": {
                "debtorId": "123456",
                "emailAddress": "example@example.com",
                "gender": "Male",
                "dateOfBirth": "1989-06-12T00:00:00.000Z",
                "socialSecurityNumber": "721-02-1234",
                "chamberOfCommerceNumber": "59750111",
                "vatNumber": "NL001234567B01"
            },
            "shippingAddress": {
                "title": "Dhr.",
                "firstName": "Henk",
                "middleName": "van",
                "lastName": "Loo",
                "countryIso3166Alpha2": "NL",
                "addressLine1": "Dorpsstraat 12",
                "addressLine2": "kamer 1",
                "zipCode": "1234AB",
                "city": "Amsterdam",
                "stateProvince": "Noord-Holland",
                "phoneNumber1": "0612345678",
                "phoneNumber1Type": "Mobile",
                "phoneNumber2": "+31687654321",
                "phoneNumber2Type": "Mobile",
                "organisation": "CashFlows",
                "department": "Venray Office"
            },
            "orderLines": [
                {
                    "lineNumber": "1",
                    "type": "PhysicalItem",
                    "skuCode": "23A18F9_M65b",
                    "name": "Chair",
                    "description": "A very good relax chair",
                    "quantity": "230",
                    "unitPriceExclVat": "23.99",
                    "unitPriceInclVat": "23.99",
                    "vatPercentage": "0.0",
                    "vatPercentageLabel": "0%",
                    "discountPercentageLabel": "0%",
                    "totalLineAmount": "23.99",
                    "url": "https://www.example.com/product/2348019/Super_chair.html"
                }
            ]
        },
        "recurringPaymentJobReference": "190321121911244096",
        "paymentMethodsToUse": [
            "Ideal",
            "PayPal"
        ],
        "displayUrl": "https://www.example.com",
        "currency": "EUR",
        "amountToCollect": "23.99",
        "amountCollected": "23.99",
        "paidAmount": "23.99",
        "paidDateTimeUtc": "2019-03-12T13:03:22.432Z",
        "expirationDateTimeUtc": "2019-09-12T13:03:21.888Z",
        "flags": {
        	"flag1": "true",
            "flag2": "false"
        },
        "attributes": {
        	"attr1": "attr1",
            "attr2": "attr2"
        },
        "paymentStatus": "Pending",
        "refundStatus": "Pending",
        "reversalStatus": "NotReversed",
        "payments": [
            {
                "reference": "190321121311044296",
                "createDateTimeUtc": "190321121911044096",
                "paymentMethods": [
                    "Ideal"
                ],
                "status": "Pending",
                "amountToCollect": "23.99",
                "surchargeAmount": "0.00",
                "convertedTotalAmount": "23.99",
                "convertedCurrency": "GBP",
                "conversionRate": "1",
                "paidAmount": "23.99",
                "steps": [
                    {
                        "reference": "190321121911044296",
                        "createDateTimeUtc": "2019-03-12T13:03:22.432Z",
                        "action": "DisplayHostedPage",
                        "paymentMethods": [
                            "Ideal"
                        ],
                        "status": "Pending"
                    }
                ],
                "attributes": {
                    "attr1": "attr1",
                    "attr2": "attr2"
                },
                "refunds": [
                    {
                        "reference": "190321321921044296",
                        "createDateTimeUtc": "2019-03-12T13:03:22.432Z",
                        "creditNumber": "12345678",
                        "creditNote": "My note",
                        "status": "Pending",
                        "amountToRefund": "23.99",
                        "convertedAmountToRefund": "23.99",
                        "convertedCurrency": "GBP",
                        "conversionRate": "1",
                        "paymentReference": "190321321121044296",
                        "steps": [
                            {
                                "reference": "190321321911044296",
                                "createDateTimeUtc": "2019-03-12T13:03:22.432Z",
                                "action": "NotImplemented",
                                "status": "Pending",
                                "description": "Desc",
                                "resultAttributes": {
                                    "attr1": "attr1",
                                    "attr2": "attr2"
                                }
                            }
                        ]
                    }
                ]
            }
        ],
        "invoices": [
            {
                "reference": "190331321911044296",
                "invoiceNumber": "7893451",
                "dateTimeUtc": "2019-03-12T13:03:22.432Z",
                "offline": "false",
                "billingAddress": {
                    "title": "Dhr.",
                    "firstName": "Henk",
                    "middleName": "van",
                    "lastName": "Loo",
                    "countryIso3166Alpha2": "NL",
                    "addressLine1": "Dorpsstraat 12",
                    "addressLine2": "kamer 1",
                    "zipCode": "1234AB",
                    "city": "Amsterdam",
                    "stateProvince": "Noord-Holland",
                    "phoneNumber1": "0612345678",
                    "phoneNumber1Type": "Mobile",
                    "phoneNumber2": "+31687654321",
                    "phoneNumber2Type": "Mobile",
                    "organisation": "CashFlows",
                    "department": "Venray Office"
                },
                "billingIdentity": {
                    "debtorId": "123456",
                    "emailAddress": "example@example.com",
                    "gender": "Male",
                    "dateOfBirth": "1989-06-12T00:00:00.000Z",
                    "socialSecurityNumber": "721-02-1234",
                    "chamberOfCommerceNumber": "59750111",
                    "vatNumber": "NL001234567B01"
                },
                "shipmentTrackAndTraceInfo": {
                    "trackingNumber": "S3489TRPL",
                    "trackingUrl": "https://postnl.nl/track&trace?ref=S3489TRPL",
                    "shippingCompany": "PostNL",
                    "shippingMethod": "Standard"
                },
                "returnTrackAndTraceInfo": {
                    "trackingNumber": "S3490TRPL",
                    "trackingUrl": "https://postnl.nl/track&trace?ref=S3490TRPL",
                    "shippingCompany": "PostNL",
                    "shippingMethod": "Standard"
                },
                "totalInvoiceAmount": "1.0",
                "invoiceLines": [
                    {
                        "lineNumber": "1",
                        "type": "Physical Item",
                        "skuCode": "s1234t78",
                        "name": "Hooverboard",
                        "description": "A really cool hooverboard",
                        "quantity": "1",
                        "unitPriceExclVat": "23.99",
                        "unitPriceInclVat": "29.03",
                        "VatPercentage": "21",
                        "VatPercentageLabel": "21 %",
                        "discountPercentageLabel": "0 %",
                        "totalLineAmount": "29.03",
                        "url": "https://mywebshop.magento.com/products/s1234t78",
                        "invoicedQuantity": "1",
                        "totalInvoicedLineAmount": "29.03",
                    }
                ]
            }
        ],
        "reversals": [
            {
                "dateTimeUtc": "2019-03-12T13:03:22.432Z",
                "reversedAmount": "23.99",
                "currency": "EUR",
                "paymentReference": "190321322311044296",
                "originatingPaymentMethod": "Ideal",
                "description": "Desc",
                "resultAttributes": {
                    "attr1": "attr1",
                    "attr2": "attr2"
                }
            }
        ],
        "splitOutpayment": {
			"createDateTimeUtc": "2019-03-12T13:03:22.432Z",
            "percentageCollected": "10.2",
            "amountToSplit": "23.99",
            "amountForMerchant": "20.00",
            "amountAvailableForOutpayment": "23.99",
            "amountScheduled": "23.99",
            "amountOutpaid": "23.99",
            "outpayments": [
                {
                    "createDateTimeUtc": "2019-03-12T13:03:22.432Z",
                    "beneficiary": {
                        "customerId": "2345",
                        "bic": "bic",
                        "iban": "RABO123456",
                        "nameOnBankAccount": "H.D.K. van Loo"
                    },
                    "description": "my description",
                    "scheduledDateTimeUtc": "2019-04-12T13:03:22.432Z",
                    "outPaidDateTimeUtc": "2019-04-12T13:03:22.432Z",
                    "percentage": "10.2",
                    "amount": "23.99",
                    "status": "created",
                    "steps": [
                        {
                            "reference": "1903213293311044296",
                            "createDateTimeUtc": "2019-04-12T13:03:22.432Z",
                            "action": "NotImplemented",
                            "status": "Created",
                            "description": "desc"
                        }
                    ]
                }
            ]
        }
    },
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Query payment jobs

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.PaymentJobs.Read Or
Portal.PaymentJobs.Read.Advanced Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no
sort string (comma separated)
pagenumber integer
pagesize integer Default and maximum 100
fulltext string
createdatetimeutc string/date-time (ISO 8601) Default filter condition [eq]
currency string/ECurrency Default filter condition [eq]
paymentstatus string/EPaymentStatus Default filter condition [eq]
paymentmethod string/EPaymentMethod Default filter condition [in]
amounttocollect string/decimal Default filter condition [eq]
customerreference string/int64 Default filter condition [eq]

Syntax

  • Sorting: provide fields comma separated with optionally + (ascending) or - (descending) to indicate order

    • sort=+field,-field
    • Supported sorting fields (case-insensitive):

      • Reference
      • CreateDateTimeUtc or CreateDateTime or CreateDate
      • PaymentStatusor Status
      • AmountToCollect or Amount
      • Currency
      • PaymentMethodsToUse or PaymentMethod
      • Order.BillingAddress.FirstName or FirstName
      • Order.BillingAddress.LastName or LastName
    • Other fields are accessible via the (case-sensitive) syntax: Data.PascalCaseField
  • Paginating: provide a pagenumber and pagesize

    • pagenumber=1
    • pagesize=10
  • Filtering: provide fields together with a value and optionally a condition

    • field=value (uses default filter condition)
    • field=[condition]value
    • field=[condition]value[and][condition]value

Possible filter conditions

  • [gt] - The value of the specified field must be greater than the specified value,
  • [gte] - The value of the specified field must be greater than, or equal to, the specified value,
  • [lt] - The value of the specified field must be less than the specified value,
  • [lte] - The value of the specified field must be less than, or equal to, the specified value,
  • [eq] - The value of the specified field must be equal to the specified value,
  • [neq] - The value of the specified field must not be equal to the specified value,
  • [in] - The specified value must be in the list of values of the specified field,
  • [nin] - The specified value must not be in the list of values of the specified field

Possible operators

  • [and] - To define multiple filter values for one field

Example

/api/portal/terminals/12345/paymentjobs?fulltext=myname&createdatetimeutc=[gte]2019-01-01T00:00:00.000Z[and][lte]2019-12-31T00:00:00.000Z&currency=EUR&paymentstatus=Pending&paymentmethod=iDEAL&sort=-createdatetimeutc,+status&page=3&pagesize=20

Key Value Explanation
sort -createdatetimeutc,+status Sorts descending on 'createdatetimeutc' and ascending on 'status'
pagenumber 3 Paginate value, to return records for page 3
pagesize 20 Paginate value, to return 20 records for the requested page
fulltext myname Search for the value 'myname'
createdatetimeutc [gte]2019-01-01T00:00:00.000Z[and][lte]2019-02-28T00:00:00.000Z Filter, returns records with a date greater or equal [gte] then 2019-01-01T00:00:00.000Z and lower or equal [lte] then 2019-02-28T00:00:00.000Z
currency EUR Filter, returns records where currency equals EUR
paymentstatus Pending Filter, returns records where paymentstatus equals Pending
paymentmethod iDEAL Filter, returns records where the list of paymentmethods contains iDEAL

Possible response codes

Code Cause Body
200 One or more paymentjobs are found Response object
400 Parsing or validating failed Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
data array[PaymentJob] The data to return.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
GET
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}/paymentjobs

Request example


Response object

{
    "totalCount": 142536,
    "data": [
		{
			"reference": "190321121911044096",
			"createDateTimeUtc": "2019-03-12T13:03:21.888Z",
			"type": "Payment",
			"traceReference": "190320117314091076",
			"terminalId": "12345",
			"domain": "cashflows.com",
			"terminalMetaData": "metadata",
			"locale": "nl_NL",
			"order": {
				"orderNumber": "123123",
				"note": "Please draw something cool on the box",
				"billingAddress": {
					"title": "Dhr.",
					"firstName": "Henk",
					"middleName": "van",
					"lastName": "Loo",
					"countryIso3166Alpha2": "NL",
					"addressLine1": "Dorpsstraat 12",
					"addressLine2": "kamer 1",
					"zipCode": "1234AB",
					"city": "Amsterdam",
					"stateProvince": "Noord-Holland",
					"phoneNumber1": "0612345678",
					"phoneNumber1Type": "Mobile",
					"phoneNumber2": "+31687654321",
					"phoneNumber2Type": "Mobile",
					"organisation": "CashFlows",
					"department": "Venray Office"
				},
				"billingIdentity": {
					"debtorId": "123456",
					"emailAddress": "example@example.com",
					"gender": "Male",
					"dateOfBirth": "1989-06-12T00:00:00.000Z",
					"socialSecurityNumber": "721-02-1234",
					"chamberOfCommerceNumber": "59750111",
					"vatNumber": "NL001234567B01"
				},
				"shippingAddress": {
					"title": "Dhr.",
					"firstName": "Henk",
					"middleName": "van",
					"lastName": "Loo",
					"countryIso3166Alpha2": "NL",
					"addressLine1": "Dorpsstraat 12",
					"addressLine2": "kamer 1",
					"zipCode": "1234AB",
					"city": "Amsterdam",
					"stateProvince": "Noord-Holland",
					"phoneNumber1": "0612345678",
					"phoneNumber1Type": "Mobile",
					"phoneNumber2": "+31687654321",
					"phoneNumber2Type": "Mobile",
					"organisation": "CashFlows",
					"department": "Venray Office"
				},
				"orderLines": [
					{
						"lineNumber": "1",
						"type": "PhysicalItem",
						"skuCode": "23A18F9_M65b",
						"name": "Chair",
						"description": "A very good relax chair",
						"quantity": "230",
						"unitPriceExclVat": "23.99",
						"unitPriceInclVat": "23.99",
						"vatPercentage": "0.0",
						"vatPercentageLabel": "0%",
						"discountPercentageLabel": "0%",
						"totalLineAmount": "23.99",
						"url": "https://www.example.com/product/2348019/Super_chair.html"
					}
				]
			},
			"recurringPaymentJobReference": "190321121911244096",
			"paymentMethodsToUse": [
				"Ideal",
				"PayPal"
			],
			"displayUrl": "https://www.example.com",
			"currency": "EUR",
			"amountToCollect": "23.99",
			"amountCollected": "23.99",
			"paidAmount": "23.99",
			"paidDateTimeUtc": "2019-03-12T13:03:22.432Z",
			"expirationDateTimeUtc": "2019-09-12T13:03:21.888Z",
			"flags": {
				"flag1": "true",
				"flag2": "false"
			},
			"attributes": {
				"attr1": "attr1",
				"attr2": "attr2"
			},
			"paymentStatus": "Pending",
			"refundStatus": "Pending",
			"reversalStatus": "NotReversed",
			"payments": [
				{
					"reference": "190321121311044296",
					"createDateTimeUtc": "190321121911044096",
					"paymentMethods": [
						"Ideal"
					],
					"status": "Pending",
					"amountToCollect": "23.99",
					"surchargeAmount": "0.00",
					"convertedTotalAmount": "23.99",
					"convertedCurrency": "GBP",
					"conversionRate": "1",
					"paidAmount": "23.99",
					"steps": [
						{
							"reference": "190321121911044296",
							"createDateTimeUtc": "2019-03-12T13:03:22.432Z",
							"action": "DisplayHostedPage",
							"paymentMethods": [
								"Ideal"
							],
							"status": "Pending"
						}
					],
					"attributes": {
						"attr1": "attr1",
						"attr2": "attr2"
					},
					"refunds": [
						{
							"reference": "190321321921044296",
							"createDateTimeUtc": "2019-03-12T13:03:22.432Z",
							"creditNumber": "12345678",
							"creditNote": "My note",
							"status": "Pending",
							"amountToRefund": "23.99",
							"convertedAmountToRefund": "23.99",
							"convertedCurrency": "GBP",
							"conversionRate": "1",
							"paymentReference": "190321321121044296",
							"steps": [
								{
									"reference": "190321321911044296",
									"createDateTimeUtc": "2019-03-12T13:03:22.432Z",
									"action": "NotImplemented",
									"status": "Pending",
									"description": "Desc",
									"resultAttributes": {
										"attr1": "attr1",
										"attr2": "attr2"
									}
								}
							]
						}
					]
				}
			],
			"invoices": [
				{
					"reference": "190331321911044296",
					"invoiceNumber": "7893451",
					"dateTimeUtc": "2019-03-12T13:03:22.432Z",
					"offline": "false",
					"billingAddress": {
						"title": "Dhr.",
						"firstName": "Henk",
						"middleName": "van",
						"lastName": "Loo",
						"countryIso3166Alpha2": "NL",
						"addressLine1": "Dorpsstraat 12",
						"addressLine2": "kamer 1",
						"zipCode": "1234AB",
						"city": "Amsterdam",
						"stateProvince": "Noord-Holland",
						"phoneNumber1": "0612345678",
						"phoneNumber1Type": "Mobile",
						"phoneNumber2": "+31687654321",
						"phoneNumber2Type": "Mobile",
						"organisation": "CashFlows",
						"department": "Venray Office"
					},
					"billingIdentity": {
						"debtorId": "123456",
						"emailAddress": "example@example.com",
						"gender": "Male",
						"dateOfBirth": "1989-06-12T00:00:00.000Z",
						"socialSecurityNumber": "721-02-1234",
						"chamberOfCommerceNumber": "59750111",
						"vatNumber": "NL001234567B01"
					},
					"shipmentTrackAndTraceInfo": {
						"trackingNumber": "S3489TRPL",
						"trackingUrl": "https://postnl.nl/track&trace?ref=S3489TRPL",
						"shippingCompany": "PostNL",
						"shippingMethod": "Standard"
					},
					"returnTrackAndTraceInfo": {
						"trackingNumber": "S3490TRPL",
						"trackingUrl": "https://postnl.nl/track&trace?ref=S3490TRPL",
						"shippingCompany": "PostNL",
						"shippingMethod": "Standard"
					},
					"totalInvoiceAmount": "1.0",
					"invoiceLines": [
						{
							"lineNumber": "1",
							"type": "Physical Item",
							"skuCode": "s1234t78",
							"name": "Hooverboard",
							"description": "A really cool hooverboard",
							"quantity": "1",
							"unitPriceExclVat": "23.99",
							"unitPriceInclVat": "29.03",
							"VatPercentage": "21",
							"VatPercentageLabel": "21 %",
							"discountPercentageLabel": "0 %",
							"totalLineAmount": "29.03",
							"url": "https://mywebshop.magento.com/products/s1234t78",
							"invoicedQuantity": "1",
							"totalInvoicedLineAmount": "29.03",
						}
					]
				}
			],
			"reversals": [
				{
					"dateTimeUtc": "2019-03-12T13:03:22.432Z",
					"reversedAmount": "23.99",
					"currency": "EUR",
					"paymentReference": "190321322311044296",
					"originatingPaymentMethod": "Ideal",
					"description": "Desc",
					"resultAttributes": {
						"attr1": "attr1",
						"attr2": "attr2"
					}
				}
			],
			"splitOutpayment": {
				"createDateTimeUtc": "2019-03-12T13:03:22.432Z",
				"percentageCollected": "10.2",
				"amountToSplit": "23.99",
				"amountForMerchant": "20.00",
				"amountAvailableForOutpayment": "23.99",
				"amountScheduled": "23.99",
				"amountOutpaid": "23.99",
				"outpayments": [
					{
						"createDateTimeUtc": "2019-03-12T13:03:22.432Z",
						"beneficiary": {
							"customerId": "2345",
							"bic": "bic",
							"iban": "RABO123456",
							"nameOnBankAccount": "H.D.K. van Loo"
						},
						"description": "my description",
						"scheduledDateTimeUtc": "2019-04-12T13:03:22.432Z",
						"outPaidDateTimeUtc": "2019-04-12T13:03:22.432Z",
						"percentage": "10.2",
						"amount": "23.99",
						"status": "created",
						"steps": [
							{
								"reference": "1903213293311044296",
								"createDateTimeUtc": "2019-04-12T13:03:22.432Z",
								"action": "NotImplemented",
								"status": "Created",
								"description": "desc"
							}
						]
					}
				]
			}
		},
    ],
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Reporting

Export business report

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Reports.Read Or

Header parameters

Key Type Mandatory
Authorization string yes

Pattern parameters

Key Type Mandatory
reporttype string/EReportType yes

Only TransactionReport and RemittanceStatement are available on business level

Query parameters

Key Type Mandatory
locale string/ELocale no
startdate string/date-time yes
enddate string/date-time yes
filetype string/EFileType yes
accountnumber string yes (except for transaction report)

Possible response codes

Code Cause Body
200 Report created Filestream
400 Parsing or validating failed Response object
401 Unauthorized
403 Not allowed to access resource
404 Report type not found
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)
GET
/api/portal/businesses/{BusinessId}/reports/{reporttype}

Request example


Export merchant report

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Reports.Read Or

Header parameters

Key Type Mandatory
Authorization string yes

Pattern parameters

Key Type Mandatory
reporttype string/EReportType yes

RemittanceStatement is not available on merchant level

Query parameters

Key Type Mandatory
locale string/ELocale no
startdate string/date-time yes
enddate string/date-time yes
filetype string/EFileType yes
accountnumber string yes (except for transaction report)

Possible response codes

Code Cause Body
200 Report created Filestream
400 Parsing or validating failed Response object
401 Unauthorized
403 Not allowed to access resource
404 Report type not found
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)
GET
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/reports/{reporttype}

Request example


Daily Stats

Retrieve daily stats

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Statistics.Read Or
Portal.Statistics.Read.Advanced Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no
lastXDays integer yes

Possible response codes

Code Cause Body
200 Requested statistics found Response object
400 Parsing or validating failed Response object
401 Unauthorized Response object
404 No statistics found for requested period Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
data array[DailyStatistic] The data to return.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
GET
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}/daily-stats

Request example


Response object

{
    "data": [
        {
            "startDate": "2019-05-28T00:00:00Z",
            "volumeDetails": {
                "eur": "1821.92",
                "gbp": "4530.24",
                "usd": "1230.34"
           },
            "startedCount": 881,
            "successCount": 752
        },
	],
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Terminals

Retrieve terminals

Get available terminals, within a business and merchant context, for the authorised user.

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Terminals.Read Or
Portal.Terminals.Read.Advanced Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no
searchterm string
sort string (comma separated)
pagenumber integer
pagesize integer Default and maximum 1000
  • Filtering: provide a search term to filter on trade name and/or description.

    • searchterm=myname
  • Sorting: provide fields comma separated with optionally + (ascending) or - (descending) to indicate order

    • sort=+field,-field
    • Supported sorting fields (case-insensitive):

      • TradeName or Name
    • Other fields are accessible via the (case-sensitive) syntax: Configuration.PascalCaseField
  • Paginating: provide a pagenumber and pagesize

    • pagenumber=1
    • pagesize=10

Possible response codes

Code Cause Body
200 One or more terminals found Response object
400 Parsing or validating failed Response object
404 No terminals found Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
data array[Terminal] The data to return.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
GET
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals

Request example


Response object

{
    "totalCount": 12,
	"data": [
		{
			"version": 0,
			"terminalId": "12345",
			"businessId": "1",
			"merchantId": "1",
			"contractStatus": "Granted",
			"tradeName": "PayCheckout",
			"description": "PayCheckout test terminal",
			"primaryPassword": "DE6DA27F-ACFC-463B-91F7-F852FEAC256B",
			"secondaryPassword": "DD8DE8DD-4713-4EDA-8990-1980BD9F6BEA",
			"defaultPageId": 0,
			"isSandbox": true,
			"switches": {
				"SecondChanceEmailEnabled": true
			},
			"parameters": {
				"GoogleAnalyticsKey": "GA2000005",
				"DefaultReturnUrlSuccess": "https://examsple.com?1=1&success=true",
				"DefaultReturnUrlFailed": "https://example.com?a=1&failed=true",
				"DefaultWebhookUrl": "https://example.com/notifier/api/notifier-test",
				"SystemNotificationsEmail": "developer@paycheckout.com",
				"DefaultReturnUrlCancelled": "https://example.com?1=1&cancelled=true",
				"SecondChanceEmailWaitTimeMinutes": "60"
			},
			"paymentMethods": [
                {
                    "paymentMethod": "Creditcard",
                    "enabled": true
                },
                {
                    "paymentMethod": "PayPal",
                    "enabled": true
                }
            ]
		}
	],
	" errorReport ": {
		" language ": " nl_NL ",
		" isFatalError ": " true ",
		" errors ": [{
				" code ": " ErrorCode ",
				" message ": " Error message default ",
				" translatedMessage ": " Foutmelding standaard ",
				" parameters ": [
					" default "
				]
			}
		],
		" warnings ": [{
				" code ": " WarningCode_1 ",
				" message ": " Warning message default ",
				" translatedMessage ": " Waarschuwingsbericht standaard ",
				" parameters ": [
					" default "
				]
			}
		]
	}
}

Create terminal

Create a new terminal, within a business and merchant context, and receive a generated terminal id in the response.

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Terminals.Create Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Request body properties

Key Mandatory Type Remark
tradeName yes string Trade name that will be shown where this is usefull, for example in the hosted page
description no string Description for the terminal
contractStatus no string/EContractStatus The contract status of this terminal
isSandbox no boolean Indicates if this terminal is used for sandbox environment

Possible response codes

Code Cause Body
200 Terminal created
400 Parsing or validating failed Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
terminalId integer The generated terminal id assigned to newly created terminal.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
POST
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals

Request example


Request body

{
    "tradeName": "PayCheckout",
    "description": "PayCheckout test terminal",
    "contractStatus": "Granted",
    "isSandbox": true
}

Response object

{
	"terminalId": "190521004462739460",
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Retrieve terminal

Retrieve a specific terminal on terminalId

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Terminals.Read Or
Portal.Terminals.Read.Advanced Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Possible response codes

Code Cause Body
200 Requested terminal found Response object
400 Parsing or validating failed Response object
404 Requested terminal not found Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
data Terminal The data to return.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
GET
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}

Request example


Response object

{
	"data": {
		"version": 0,
		"terminalId": "12345",
		"businessId": "1",
		"merchantId": "1",
		"contractStatus": "Granted",
		"tradeName": "PayCheckout",
		"description": "PayCheckout test terminal",
		"primaryPassword": "DE6DA27F-ACFC-463B-91F7-F852FEAC256B",
		"secondaryPassword": "DD8DE8DD-4713-4EDA-8990-1980BD9F6BEA",
		"defaultPageId": 0,
		"isSandbox": true,
		"switches": {
			"SecondChanceEmailEnabled": true
		},
		"parameters": {
			"GoogleAnalyticsKey": "GA2000005",
			"DefaultReturnUrlSuccess": "https://examsple.com?1=1&success=true",
			"DefaultReturnUrlFailed": "https://example.com?a=1&failed=true",
			"DefaultWebhookUrl": "https://example.com/notifier/api/notifier-test",
			"SystemNotificationsEmail": "developer@paycheckout.com",
			"DefaultReturnUrlCancelled": "https://example.com?1=1&cancelled=true",
			"SecondChanceEmailWaitTimeMinutes": "60"
		},
		"paymentMethods": [
            {
                "paymentMethod": "Creditcard",
                "enabled": true
            },
            {
                "paymentMethod": "PayPal",
                "enabled": true
            }
        ]
	},
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Update terminal

Update the terminal specified by TerminalId.

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Terminals.Update Or
Portal.Terminals.Update.Advanced Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Request body properties

Key Mandatory Type Remark
version yes integer Not mandatory for first insert
terminalId yes string The terminal id assigned by CashFlows
businessId yes string The business id assigned by CashFlows
merchantId yes string The merchant id assigned by CashFlows
contractStatus yes string/EContractStatus The contract status of this terminal
tradeName yes string Trade name that will be shown where this is usefull, for example in the hosted page
description no string Description for the terminal
primaryPassword yes* string must be a GUID, need not be set when creating a new terminal, it will automatically be created
secondaryPassword no string must be a GUID, Change procedure allows for temporary existence of two passwords to allow migration of servers
defaultPageId yes integer PageId to use (default = 0)
isSandbox yes boolean Indicates if this terminal is used for sandbox environment
switches no object Configured switches
switches.EConfigSwitch no boolean Switch to enable or disable
parameters no object Configured parameters
parameters.EConfigParameter no string Parameter with value
paymentMethods yes array[PaymentMethodState] List of the payment method(s) to use. The order of paymentmethods indicate the order on which they appear on the hosted page.

*) primaryPassword need not be set when creating a new terminal, it will automatically be created.

Possible response codes

Code Cause Body
200 Terminal created or updated
400 Parsing or validating failed Response object
404 Terminal to update not found Response object
409 Version supplied not correct
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
PUT
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}

Request example


Request body

{
    "version": 86,
    "terminalId": "12345",
    "businessId": "1",
    "merchantId": "1",
    "contractStatus": "Granted",
    "tradeName": "PayCheckout",
    "description": "PayCheckout test terminal",
    "primaryPassword": "DE6DA27F-ACFC-463B-91F7-F852FEAC256B",
    "secondaryPassword": "DD8DE8DD-4713-4EDA-8990-1980BD9F6BEA",
    "isSandbox": true,
    "switches": {
        "secondChanceEmailEnabled": true
    },
    "parameters": {
        "googleAnalyticsKey": "GA2000005",
        "defaultReturnUrlSuccess": "https://example.com?1=1&success=true",
        "defaultReturnUrlFailed": "https://example.com?a=1&failed=true",
        "defaultWebhookUrl": "http://internal-dev-private-165961934.eu-west-1.elb.amazonaws.com/notifier/api/notifier-test",
        "systemNotificationsEmail": "developer@paycheckout.com",
        "defaultReturnUrlCancelled": "https://example.com?1=1&cancelled=true",
        "secondChanceEmailWaitTimeMinutes": "60"
    },
	"paymentMethods": [
        {
            "paymentMethod": "Creditcard",
            "enabled": true
        },
        {
            "paymentMethod": "PayPal",
            "enabled": true
        }
    ]
}

Response object

{
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Remove terminal

Removes the specified terminal

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Terminals.Delete Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Possible response codes

Code Cause Body
204 Terminal removed
400 Parsing or validating failed Response object
404 Requested terminal not found Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
DELETE
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}

Request example


Response object

{
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Creditcard Settings

Retrieve creditcard configuration

Retrieve creditcard configuration for the given terminalId.

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Terminals.Read Or
Portal.Terminals.Read.Advanced Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Possible response codes

Code Cause Body
200 Terminal creditcard configuration retrieved Response object
400 Parsing or validating failed Response object
404 Requested configuration not found Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
data.version integer Indicates the next version, to be used for updating the creditcard configuration.
data.creditcard Creditcard The data to return.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.

Remark: Be aware that the creditcard class can be retrieved as empty, if creditcard is not configured. If you want to set Creditcard configuration you must use the version returned.

GET
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}/creditcard

Request example


Response object

{
	"data": {
		"version" : 3,
		"creditcard": {
            "skip3DSecure": false,
            "disallowNon3DSecure": false,
            "autoCapture": true,
            "allowDirectAcquiring": false,
            "contractStatus": "Granted",
            "currencySettings": {
                "eur": {
                    "surcharge": {
                        "fixedAmount": "1",
                        "minimumAmount": "2",
                        "percentage": "3",
                        "vatPercentage": "4"
                    },
                    "minMaxLimit": {
                        "minimumCharge": "0.05",
                        "maximumCharge": "5000.0"
                    }
                }
            },
            "dynamicSettlementTiming": {
                "2018-12-01T00:00:00": {
                    "relativeHoursAfterAuthorisation": 15
                }
            }
        }
    },
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Update creditcard configuration

Update the creditcard configuration for the specified terminal.

Remark: Always read the creditcard information first in order to correctly populate the version parameter in a subsequent put request.

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Terminals.Update Or
Portal.Terminals.Update.Advanced Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Request body properties

Key Mandatory Type Remark
version yes integer Needed for subsequent update
creditcard No object Configuration of credit cards
creditcard.skip3DSecure yes boolean If true, no 3DS enrollment checks are made (if allowed by the acquirer)
creditcard.disallowNon3DSecure yes boolean If true, payments for cards that are not 3DSecure enrolled are disallowed (if not already enforced by the acquirer)
creditcard.autoCapture yes boolean If true, capture payment immediatly after authorisation; if false, reservation only
creditcard.currencySettings no CurrencySettings
creditcard.currencySettings.* no ECurrency
creditcard.currencySettings.*.surcharge no Surcharge
creditcard.currencySettings.*.surcharge.fixedAmount no string/decimal
creditcard.currencySettings.*.surcharge.minimumAmount no string/decimal
creditcard.currencySettings.*.surcharge.percentage no string/decimal
creditcard.currencySettings.*.surcharge.vatPercentage no string/decimal
creditcard.currencySettings.*.minMaxLimit no MinMaxLimit
creditcard.currencySettings.*.minMaxLimit.minimumCharge yes string/decimal
creditcard.currencySettings.*.minMaxLimit.maximumCharge yes string/decimal

Possible response codes

Code Cause Body
204 Terminal creditcard configuration stored
400 Parsing or validating failed Response object
404 Requested configuration not found Response object
409 Version supplied not correct
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
PUT
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}/creditcard

Request example


Request body

{
    "version" : 0,
    "creditcard": {
        "skip3DSecure": false,
        "disallowNon3DSecure": false,
        "autoCapture": true,
        "currencySettings": {
            "eur": {
                "surcharge": {
                    "fixedAmount": "1",
                    "minimumAmount": "2",
                    "percentage": "3",
                    "vatPercentage": "4"
                },
                "minMaxLimit": {
                    "minimumCharge": "0.05",
                    "maximumCharge": "5000.0"
                }
            }
        },
        "dynamicSettlementTiming": {
            "2018-12-01T00:00:00": {
                "relativeHoursAfterAuthorisation": 15
            }
        }
    }
}

Response object

{
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

PayPal Settings

Retrieve PayPal configuration

Retrieves the PayPal configuration for the specified terminal.

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Terminals.Read Or
Portal.Terminals.Read.Advanced Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Possible response codes

Code Cause Body
200 Terminal paypal configuration retrieved Response object
400 Parsing or validating failed Response object
404 Requested configuration not found Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
data.version integer Indicates the next version, to be used for updating the PayPal configuration.
data.payPal PayPal The data to return.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.

Remark: Be aware that the PayPal class can be retrieved as empty, if paypal is not configured. If you want to set PayPal configuration you must use the version returned.

GET
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}/paypal

Request example


Response object

{
	"data": {
		"version" : 3,
		"payPal": {
            "merchantId": "merchant@business.co.uk",
            "autoCapture": true,
            "contractStatus": "Granted",
            "currencySettings": {
                "eur": {
                    "surcharge": {
                        "fixedAmount": "1",
                        "minimumAmount": "2",
                        "percentage": "3",
                        "vatPercentage": "4"
                    },
                    "minMaxLimit": {
                        "minimumCharge": "0.05",
                        "maximumCharge": "5000.0"
                    }
                }
            }
        }
	},
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Update PayPal configuration

Update the PayPal configuration for the specified terminal.

Remark: Always read the PayPal information first in order to correctly populate the version parameter in a subsequent put request.

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Terminals.Update Or
Portal.Terminals.Update.Advanced Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Request body properties

Key Mandatory Type Remark
version yes int Needed for subsequent update
payPal No object
payPal.merchantId yes string The merchant id of the seller account linked with the CashFlows account at PayPal
payPal.autoCapture yes bool Set this property to true to automatically and immediately capture a payment after authorization
payPal.currencySettings no CurrencySettings
payPal.currencySettings.* no ECurrency
payPal.currencySettings.*.surcharge no Surcharge
payPal.currencySettings.*.surcharge.fixedAmount no string/decimal
payPal.currencySettings.*.surcharge.minimumAmount no string/decimal
payPal.currencySettings.*.surcharge.percentage no string/decimal
payPal.currencySettings.*.surcharge.vatPercentage no string/decimal
payPal.currencySettings.*.minMaxLimit no MinMaxLimit
payPal.currencySettings.*.minMaxLimit.minimumCharge yes string/decimal
payPal.currencySettings.*.minMaxLimit.maximumCharge yes string/decimal

Possible response codes

Code Cause Body
204 Terminal paypal configuration stored
400 Parsing or validating failed Response object
404 Requested configuration not found Response object
409 Version supplied not correct
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
PUT
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}/paypal

Request example


Request body

{
    "version" : 0,
    "payPal": {
        "merchantId": "merchant@business.co.uk",
        "autoCapture": true,
        "currencySettings": {
            "eur": {
                "surcharge": {
                    "fixedAmount": "1",
                    "minimumAmount": "2",
                    "percentage": "3",
                    "vatPercentage": "4"
                },
                "minMaxLimit": {
                    "minimumCharge": "0.05",
                    "maximumCharge": "5000.0"
                }
            }
        }
    }
}

Response object

{
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Hosted Pages

Retrieve hosted page configuration

Retrieves the hosted pages configuration for the specified terminal.

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Terminals.Read Or
Portal.Terminals.Read.Advanced Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Possible response codes

Code Cause Body
200 Terminal paypal configuration retrieved Response object
400 Parsing or validating failed Response object
404 Requested configuration not found Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
data.version integer Indicates the next version, to be used for updating the creditcard configuration.
data.hostedPages HostedPages The data to return.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.

HostedPages

Hosted pages consists of one of more id-fields with a hosted page as value.

Key Type
int HostedPage

Remark: Be aware that the hosted page class can be retrieved as empty, if hosted page is not configured. If you want to set hoted page configuration you must use the version returned.

GET
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}/hosted-pages

Request example


Response object

{
	"data": {
		"version" : 0,
        "hostedPages": {
            "1": {
                "useCustomLogo": false,
                "customLogoReference": "190428000150994944",
                "useCustomFavicon": false,
                "customFaviconReference": "190428000150994945",
                "thumbnailReference": "190428000150884844",
                "settings": "string",
                "useCustomCss": false,
                "customCss": "body: green",
            }
        }
	},
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Create/Update hosted pages configuration

Create or update the hosted pages configuration for the specified terminal.

Remark: Always read the hosted pages information first in order to correctly populate the version parameter in a subsequent put request.

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Terminals.Update Or
Portal.Terminals.Update.Advanced Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Request body properties

Key Mandatory Type Remark
version yes integer Needed for subsequent update
hostedPages no HostedPagesCollection
hostedPages.[*].useCustomLogo no boolean Indicates whether to use the custom logo.
hostedPages.[*].customLogoReference no string/int64 Unique reference to the custom logo image.
hostedPages.[*].useCustomFavicon no boolean Indicates whether to use the custom favicon.
hostedPages.[*].customFaviconReference no string/int64 Unique reference to the custom favicon image.
hostedPages.[*].thumbnailReference no string/int64 Unique reference to the thumbnail image.
hostedPages.[*].settings no string General settings.
hostedPages.[*].useCustomCss no boolean Indicates whether to use the custom css.
hostedPages.[*].customCss no string Custom CSS to overwrite/extend the default CSS with.

HostedPagesCollection

Hosted pages consists of one of more id-fields with a hosted page as value.

Key Mandatory Type
int no HostedPage

Possible response codes

Code Cause Body
204 Terminal hosted page configuration stored
400 Parsing or validating failed Response object
404 Requested configuration not found Response object
409 Version supplied not correct
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
PUT
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}/hosted-pages

Request example


Request body

{
    "version" : 0,
    "hostedPages": {
        "1": {
            "useCustomLogo": false,
            "customLogoReference": "190428000150994944",
            "useCustomFavicon": false,
            "customFaviconReference": "190428000150994945",
            "thumbnailReference": "190428000150884844",
            "settings": "string",
            "useCustomCss": false,
            "customCss": "body: green",
        }
    }
}

Response object

{
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Remove hosted pages configuration

Removes the hosted pages configuration for the specified terminal.

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Terminals.Delete Or
Portal.Terminals.Update Or
Portal.Terminals.Update.Advanced Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Possible response codes

Code Cause Body
204 Terminal hosted page configuration removed
400 Parsing or validating failed Response object
404 Requested configuration not found Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
DELETE
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}/hosted-pages

Request example


Response object

{
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Campaigns

Retrieve one campaign

Retrieve a campaign by providing terminal id and campaign reference.

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Campaigns.Read Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Possible response codes

Code Cause Body
200 Requested campaign found Response object
400 Parsing or validating failed Response object
404 Requested campaign not found Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
data Campaign The data to return.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
GET
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}/campaigns/{CampaignReference}

Request example


Response object

{
    "data": {
    	"reference": "string/long",
        "domain": "string",
        "terminalId": "string",
        "name": "string",
        "startUtc": "string/datetime",
        "endUtc": "string/datetime",
        "pageIds": [
            123,
        ],
        "pageStatistics": [
            {
                "pageId": 123,
                "startedCount": 25,
                "successCount": 25,
                "avgTimeToSuccessMs": 1000,
                "minTimeToSuccessMs": 500,
                "maxTimeToSuccessMs": 2000
            },
        ]
    },
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Retrieve campaigns

Retrieve all campaigns for a domain and terminal.

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Campaigns.Read Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Possible response codes

Code Cause Body
200 Campaigns found Response object
400 Parsing or validating failed Response object
404 No campaigns found Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
data array[Campaign] The data to return.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
GET
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}/campaigns

Request example


Response object

{
    "data": [
        {
            "reference": "string/long",
            "domain": "string",
            "terminalId": "string",
            "name": "string",
            "startUtc": "string/datetime",
            "endUtc": "string/datetime",
            "pageIds": [
                123,
            ],
            "pageStatistics": [
                {
                    "pageId": 123,
                    "startedCount": 25,
                    "successCount": 25,
                    "avgTimeToSuccessMs": 1000,
                    "minTimeToSuccessMs": 500,
                    "maxTimeToSuccessMs": 2000
                },
            ]
        },
    ],
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Create a new campaign

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Campaigns.Create Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Request body properties

Key Type Mandatory Remark
name string yes Name of the campaign.
startUtc string/datetime yes Date and time the campaign will start
endUtc string/datetime yes Date and time the campaign will end
pageIds array[integer] yes Id's of the payment pages that will be used during the campaign

Possible response codes

Code Cause Body
201 Campaign created
400 Parsing or validating failed Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
POST
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}/campaigns

Request example


Request body

{
	"name": "string",
	"startUtc": "string/datetime",
	"endUtc": "string/datetime",
	"pageIds": [
		123,
	]
}

Response object

{
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Update a campaign

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Campaigns.Update Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Request body properties

Key Type Mandatory Remark
name string yes Name of the campaign.
startUtc string/datetime yes Date and time the campaign will start
endUtc string/datetime yes Date and time the campaign will end
pageIds array[integer] yes Id's of the payment pages that will be used during the campaign

Possible response codes

Code Cause Body
204 Campaign updated
400 Parsing or validating failed Response object
404 Requested campaign not found Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
PUT
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}/campaigns/{CampaignReference}

Request example


Request body

{
	"name": "string",
	"startUtc": "string/datetime",
	"endUtc": "string/datetime",
	"pageIds": [
		int,
	]
}

Response object

{
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Stop a campaign

Immediately stops a campaign. Sets the end time of a campaign to the current UTC time.

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Campaigns.Update Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Possible response codes

Code Cause Body
204 Campaign stopped
400 Parsing or validating failed Response object
404 Requested campaign not found Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
POST
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}/campaigns/{CampaignReference}/stop

Request example


Response object

{
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Remove a campaign

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Campaigns.Delete Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Possible response codes

Code Cause Body
204 Campaign deleted
400 Parsing or validating failed Response object
404 Requested campaign not found Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
DELETE
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}/campaigns/{CampaignReference}

Request example


Response object

{
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Customers

The portal api provides endpoints for managing customers. Customers are a helpful tool to make it easier to process mo/to transactions, but can aid in other parts of the business as well, such as refunds, recurring payments or marketing.

Retrieve one customer

Retrieve a customer by providing terminal id and customer reference.

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Customers.Read Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Possible response codes

Code Cause Body
200 Requested customer found Response object
400 Parsing or validating failed Response object
404 Requested customer not found Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
data Customer The data to return.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
GET
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}/customers/{CustomerReference}

Request example


Response object

{
    "data": {
    	"reference": "string/long",
        "domain": "string",
        "terminalId": "string",
        "billingAddress": {
          "title": "Mr.",
          "firstName": "John",
          "middleName": "Van",
          "lastName": "Dijk",
          "countryIso3166Alpha2": "GB",
          "addressLine1": "Business Centre Road",
          "addressLine2": "Unit 7",
          "zipCode": "XX12 1XX",
          "city": "TestCity",
          "phoneNumber1": "+44 9999 123456",
          "phoneNumber1Type": "Fixed",
          "phoneNumber2": "+44 8888 123456",
          "phoneNumber2Type": "Unknown",
          "organisation": "Sample Business Ltd"
        },
        "billingIdentity": {
            "debtorId": "debtorId",
            "emailAddress": "John.Doe@example.com",
            "gender": "Male"
        },
        "shippingAddress": {
          "title": "Mr.",
          "firstName": "John",
          "middleName": "Van",
          "lastName": "Dijk",
          "countryIso3166Alpha2": "GB",
          "addressLine1": "Airfield Lane 4",
          "addressLine2": "",
          "zipCode": "XX12 1XX",
          "city": "TestCity",
          "phoneNumber1": "+44 9999 777777",
          "phoneNumber1Type": "Fixed"
        }
    },
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Query customers

Retrieve multiple customers for a domain and terminal based on search criteria.

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Customers.Read Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no
sort string (comma separated)
pagenumber integer
pagesize integer default and maximum 100
fulltext string

Syntax

  • Sorting: provide fields comma separated with optionally + (ascending) or - (descending) to indicate order

    • sort=+field,-field
    • Supported sorting fields (case-insensitive):

      • FirstName
      • LastName
    • Other fields are accessible via the (case-sensitive) syntax: Data.PascalCaseField
  • Paginating: provide a page and pagesize

    • pagenumber=1
    • pagesize=10
  • Filtering: provide one or more fulltext searchvalues (seperated by a +)

    • fulltext=value
    • fulltext=value1+value2

Example

/api/portal/terminals/12345/customers?sort=+lastname&page=3&pagesize=20

Key Value Explanation
sort +lastname Sorts ascending on 'lastname'
pagenumber 3 Paginate value, to return records for page 3
pagesize 20 Paginate value, to return 20 records for the requested page

Possible response codes**

Code Cause Body
200 Customers found Response object
400 Parsing or validating failed Response object
404 No customers found Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
data array[Customer] The data to return.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
GET
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}/customers

Request example


Response object

{
    "data": [
        {
            "reference": "string/long",
            "domain": "string",
            "terminalId": "string",
            "billingAddress": {
                "pageId": 123,
                "startedCount": 25,
                "successCount": 25,
                "avgTimeToSuccessMs": 1000,
                "minTimeToSuccessMs": 500,
                "maxTimeToSuccessMs": 2000
            },
            "billingIdentity": {
                
            },
            "shippingAddress": {
                
            }
        },
    ],
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Export customers

Export customers for a domain and terminal based on search criteria.

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Customers.Read Or

Header parameters

Key Type Mandatory Remark
Content-Type string yes Supported types: text/csv
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no
sort string (comma separated)
fulltext string

Syntax

  • Sorting: provide fields comma separated with optionally + (ascending) or - (descending) to indicate order

    • sort=+field,-field
    • Supported sorting fields (case-insensitive):

      • FirstName
      • LastName
    • Other fields are accessible via the (case-sensitive) syntax: Data.PascalCaseField
  • Filtering: provide one or more fulltext searchvalues (seperated by a +)

    • fulltext=value
    • fulltext=value1+value2

Possible response codes

Code Cause Body
200 Customers found export.csv attachment
400 Parsing or validating failed Response object
404 No customers found Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
GET
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}/customers

Request example


Create a new customer

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Customers.Create Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Request body properties

Key Type Mandatory Remark
root Customer yes The customer data to create.

Possible response codes

Code Cause Body
201 Customer created
400 Parsing or validating failed Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
data Customer The created customer.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
POST
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}/customers

Request example


Request body

{
	"billingAddress": {
        "firstName": "John",
        "lastName": "Doe"
    }
}

Response object

{
    "data": {
    	"reference": "190629000176291843",
        "terminalId": "string",
        "domain": "string",
        "billingAddress": {
            "firstName": "John",
            "lastName": "Doe"
        }
	},
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Update a customer

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Customers.Update Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Request body properties

Key Type Mandatory Remark
root Customer yes Data to update the customer with.

Possible response codes

Code Cause Body
204 Customer updated
400 Parsing or validating failed Response object
404 Requested customer not found Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
data Customer The updated data of the customer.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
PUT
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}/customers/{CustomerReference}

Request example


Request body

{
	"billingAddress": {
        "firstName": "John",
        "lastName": "Doe"
    }
}

Response object

{
     "data": {
    	"reference": "190629000176291843",
        "terminalId": "string",
        "domain": "string",
        "billingAddress": {
            "firstName": "John",
            "lastName": "Doe"
        }
	},
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Remove a customer

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Customers.Delete Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Possible response codes

Code Cause Body
204 Customer deleted
400 Parsing or validating failed Response object
404 Requested customer not found Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
DELETE
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}/customers/{CustomerReference}

Request example


Response object

{
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Retrieve customer data

Customers can have arbitrary data associated with them that can be retrieved using the endpoint below. The data is stored using key value pairs. The key indicates the type of data and can occur more than once.

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Customers.Read Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Possible response codes

Code Cause Body
200 Requested customer found Response object
400 Parsing or validating failed Response object
404 Requested customer not found Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
data array[KeyJsonValuePair] An array with key value pairs.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
GET
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}/customers/{CustomerReference}/data

Request example


Response object

{
    "data": [
        {
            "key": "CreditcardToken",
            "value": "{\"token\":\"1000000000030419\",\"expiryDateMonth\":\"02\",\"expiryDateYear\":\"09\",\"description\":\"400000****0002\"}"
        },
        {
            "key": "CreditcardToken",
            "value": "{\"token\":\"1000000000030419\",\"expiryDateMonth\":\"02\",\"expiryDateYear\":\"16\",\"description\":\"400000****0002\"}"
        },
        {
            "key": "CreditcardToken",
            "value": "{\"token\":\"1000000000030419\",\"expiryDateMonth\":\"02\",\"expiryDateYear\":\"24\",\"description\":\"400000****0002\"}"
        }
    ],
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Remove customer data

Customer data can be removed one at a time by using the index of the data, or all at once by omitting the index and calling the endpoint directly.

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Customers.Update Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Possible response codes

Code Cause Body
204 Customer deleted
400 Parsing or validating failed Response object
404 Requested customer not found Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
DELETE
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}/customers/{CustomerReference}/data[/{Index}]

Request example


Response object

{
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

User Settings

User settings can be used to store arbitrary settings per user, for instance to ensure consistency of portal ui settings for a user across browsers or computers.

Retrieve user setting

Gets a user setting for current domain, logged in user and specified key.

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Settings.Read Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Possible response codes

Code Cause Body
200 Requested user setting found Response object
400 Parsing or validating failed Response object
404 Requested user setting not found Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
data UserSetting The setting to return.
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
GET
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/user-settings/{Key}

Request example


Response object

{
    "data": {
        "value": "string"
    },
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Create/Update user setting

Save a new or update existing user setting for current domain, logged in user and specified key.

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Settings.Create Or
Portal.Settings.Update Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Request body properties

Key Type Mandatory Remark
value string yes A string with settings

Possible response codes

Code Cause Body
200 User setting created or updated
400 Parsing or validating failed Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
PUT
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/user-settings/{Key}

Request example


Request body

{
    "value": "string"
}

Response object

{
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Delete user setting

Delete an existing user setting for the current domain, logged in user and specified key.

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Settings.Delete Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Possible response codes

Code Cause Body
204 User setting deleted
400 Parsing or validating failed Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
DELETE
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/user-settings/{Key}

Request example


Response object

{
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Images

Retrieve image

Retrieve the image for the provided reference. This endpoint does not need an authorization header.

Query parameters

Key Type Mandatory
locale string/ELocale no

Possible response codes

Code Cause Body
200 Requested image retrieved Image
400 Parsing or validating failed Response object
404 Requested image not found Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
GET
/api/portal/images/{Reference}

Request example


Response object

{
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	}
}

Store image

Stores an image and receive the unique reference in the response.

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Terminals.Update Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Request body properties

Key Mandatory Type Remark
data yes string/base64 Binary representation of the image
mimeType yes string Mime-type of the image
filename no string Filename of the image

Possible response codes

Code Cause Body
204 Image stored
400 Parsing or validating failed Response object
401 The user is not authorized
403 The user does not have the correct permissions to perform this action
404 Requested image not found Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
reference string/int64 Unique reference of the stored image
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
POST
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}/images

Request example


Request body

{	
    "mimeType": "image/jpeg",
    "data": "aW1hZ2U=",
    "filename": "filename.jpg"
}

Response object

{
    "reference": "190428000150994944",
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Remove image

Removes the image with provided reference.

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Required Permissions

Permission Logic
Portal.Terminals.Update Or

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Possible response codes

Code Cause Body
204 Image removed
400 Parsing or validating failed Response object
401 The user is not authorized
403 The user does not have the correct permissions to perform this action
404 Requested image not found Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
DELETE
/api/portal/businesses/{BusinessId}/merchants/{MerchantId}/terminals/{TerminalId}/images/{Reference}

Request example


Response object

{
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Bug Report

Send bug report

Send a bug report.

Machine scope(s)

Scope Remark
PortalApi Machine clients with this scope are accepted

Header parameters

Key Type Mandatory
Authorization string yes

Query parameters

Key Type Mandatory
locale string/ELocale no

Request body properties

Key Type Mandatory Remark
bug-report string yes A valid json string

Possible response codes

Code Cause Body
200 Bug report queued for mail sender
400 Parsing or validating failed Response object
500 Internal error (general)
503 One of the required services are offline
504 Gateway timeout (aws)

Response object fields

Key Type Remark
errorReport ErrorReport Report containing all warnings and errors that occurred during processing the request.
links Links Object containing relevant links.
POST
/api/portal/bug-reports

Request example


Request body

{
    bug-report
}

Response object

{
	"errorReport": {
		"language": "nl_NL",
		"isFatalError": true,
		"errors": [
			{
				"code": "ErrorCode",
				"message": "Error message default",
				"translatedMessage": "Foutmelding standaard",
				"parameters": [
					"default"
				]
			}
		],
		"warnings": [
			{
				"code": "WarningCode_1",
				"message": "Warning message default",
				"translatedMessage": "Waarschuwingsbericht standaard",
				"parameters": [
					"default"
				]
			}
		]
	},
    "links": {
    	"data": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"action": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    	"documentation": {
    		"url": "http://google.com",
    		"type": "html/text"
    	},
    }
}

Models

These are the models and enumerations used in the APIs.

AbuseReport

Main class for abuse reports.

Name Type Description
score string/decimal The score of the report.
triggers array[AbuseTrigger] The triggers that make up this report.
createdDateTimeUtc string/DateTime The date and time of creation of this report.

AbuseTrigger

Name Type Description
score string/decimal The score for this trigger, can be positive or negative.
code string The code of the trigger.
description string The description of the trigger.
parameters array[string] The parameters that caused this trigger.

Access

An object containing access information of a logged in user.

Name Type Description
credentials Credentials
userInfo UserInfo

AccountUpdateResult

Result object of a request or retrieve account update.

Name Type Description
requestId string Unique ID returned to be used to retrieve results of an account update request.
merchantId string The merchant number from the original request.
status string/EStatus The current state of the request.
results array[CreditcardUpdateResult] List of results.

CreditcardUpdateResult

Result object of a request or retrieve account update.

Name Type Description
oldCardNumber string The original card number.
oldExpiryDate string The original expiry date.
newCardNumber string The new card number.
newExpiryDate string The new expiry date.
vauRawResponse VauRawResponse Visa only. See object definition below.
abuRawResponse AbuRawResponse Mastercard only. See object definition below.
status string/EStatus The current state of the creditcard update result.

VauRawResponse

Name Type Description
responseCode string/EResponseCode The code returned by Visa

EResponseCode

Value Description
A Account number change (the account number or account number and expiration date are updated).
C Closed account advice.
E Expiration date change.
N Non-participating BIN.
P Participating BIN, no match.
Q Contact cardholder advice (the merchant should contact the cardholder for additional information on the account).
V Match made, account number and expiration date unchanged.

AbuRawResponse

Name Type Description
reasonIdentifier string/EReasonIdentifier The reaseon ident returned by Mastercard.
responseIndicator string/EResponseIndicator The indicator returned by Mastercard.

EReasonIdentifier

Value Description
Update Match made; update data provided (includes issuer Reason Codes R, B, and P).
Contac Match made; account closed (includes Issuer Reason Code C).
Expiry Match made; expiration date changed (includes Issuer Reason Code E).
Valid No updates were found but the account is valid.
Unknwn The account number could not be found in the ABU database.

EResponseIndicator

Value Description
B Brand Flip to Mastercard match.
C Closed account.
E Update expiration date.
N No match, non-participating BIN/issuer.
P No match, participating BIN/ issuer.
R Replacement card.
V Match made, account number and expiration date unchanged.

Address

An object containing information such as the name of a person, and the number of the house, name of the road, and name of the town where that person lives.

Name Type Description
title string A prefix or suffix added to someone's name in certain contexts. For example "Mr." or "Ms."/"Mrs." for an adult man or woman. This value is used "as is", regardless of the locale specified in the payment job.
firstName string The given name of the addressee.
middleName string The middle part of the name of the addressee. This is the portion of a personal name that is written between the person's given name and their surname.
lastName string The last part of the name of the addressee. This usually is the person's surname.
countryIso3166Alpha2 string/ECountry The country, using the two-letter country code as defined in the ISO 3166-1 alpha 2 definition.
addressLine1 string Primary address information, such as street name and house number.
addressLine2 string Additional address information, such as floor number or apartment number.
zipCode string The zip or postal code.
city string The name of the city.
stateProvince string The name of the state or province.
phoneNumber1 string Primary telephone number type.
phoneNumber1Type string/EPhoneNumberType Primary telephone number type.
phoneNumber2 string Secondary telephone number of the addressee.
phoneNumber2Type string/EPhoneNumberType Secondary telephone number type.
organisation string Name of the company or organization, if the address is a company or organization.
department string Name of the department, if the address is a company or organization.

Campaign

A campaign

Name Type Description
reference long Unique reference of this campaign.
domain string Domain where the campaign belongs to.
terminalId string Id of the site or service the campaign is associated with.
name string Name of the campaign.
startUtc string/datetime Date and time the campaign will start.
endUtc string/datetime Date and time the campaign will end.
pageIds array[integer] Ids of the payment pages that will be used during the campaign.
pageStatistics array[PageStatistics] Summary of page statistics.

Capture

An object that contains information about capture operations performed on the payment

Name Type Description
reference long Unique reference of this campaign.
createDateTimeUtc DateTime Time of creation of this capture
status string/ECaptureStatus Id of the site or service the campaign is associated with.
amountToCapture string Decimal number representing amount to capture
convertedAmountToCapture null string
convertedCurrency null string/ECurrency
conversionRate null string
isFinalCapture boolean true then it is the final capture, false there will be more captures

Country

Name Type Description
alpha2Code string The ISO 3166-1 alpha-2: two-letter country code.
numericCode int The numeric ISO 3166-1 code of the country.
fullName string The symbol of the currency.
translatedFullName string The full name of the country in the requested language.

Credentials

An object containing credentials for logged in user, such as access token, refresh token etc.

Name Type Description
accessToken string The created access token.
validUntilUtc string/DateTime The date time the access token can be used.
refreshToken string The refresh token that can be used to obtain a new access token.
IdToken string The id token (needed to logout).

Creditcard

Info for credit cards.

Name Type Description
skip3DSecure bool When this property is set, no 3DS enrollment checks are made (if allowed by the acquirer).
disallowNon3DSecure bool When this property is set, payments for cards that are not 3DSecure enrolled are disallowed (if not already enforced by the acquirer).
autoCapture bool Set this property to true to automatically and immediately capture a payment after authorization.
allowDirectAcquiring bool When this property is set to true, merchant is allowed to perform direct payments, supplying all creditcard data at the start of a payment.
contractStatus string/EContractStatus The contract status of this payment method.
currencySettings CurrenciesSettings Individual settings per currency.
dynamicSettlementTiming DynamicSettlementTimings Dynamic settlement timing settings.
enableAbuseChecks bool Indicates whether abuse checks should be executed for this payment type.
abuseScoreBlockThreshold string/decimal The score (0-100) at which a payment should be rejected.

CreditcardTokenizationResponse

Response on a tokensation request

Name Type Description
token string Created token
cardExpiryMonth string Validated expiry month
cardExpiryYear string Validated expiry year
truncatedCardNumber string Truncated creditcard number

Currency

Name Type Description
alpha3Code string The ISO-4217 alpha-3 code of the currency.
numericCode int The numeric ISO-4217 code of the currency.
symbol string The symbol of the currency.
numberOfDecimalPlaces int The number of decimal places for this currency.

CurrenciesSettings

Currency settings consists of one or more currency fields with currency settings as value.

Name Type Description
ECurrency CurrencySettings Currency specific settings

CurrencySettings

Name Type Description
surcharge Surcharge The configured surcharge values for this currency.
minMaxLimit MinMaxLimit The configured minimum- and maximum limit for this currency.

Customer

Name Type Description
reference string/int64 A unique reference of this customer.
terminalId string The id of the site or service the customer is associated with.
domain string The domain where the request arrived on.
billingAddress Address The address of the customer.
billingIdentity Identity Additional details of the customer.
shippingAddress Address The shipping address of the customer.

DailyStatistic

Daily statistics summary.

Name Type Description
startDate string/datetime Date of this statistics summary.
volumeDetails array[VolumeDetails] Collected amounts per currency.
startedCount integer Total count of started payment jobs.
successCount integer Total succeeded payment jobs.

VolumeDetails

Volume details consists of one of more currency fields with a decimal as value.

Name Type Description
string/ECurrency decimal Total collected amount per currency.

DynamicSettlementTimings

Dynamic settlement timings consists of one or more date-time fields with a dynamic settlement timing as value

Name Type Description
string/date-time DynamicSettlementTiming Starting date and time of the settings

DynamicSettlementTiming

Name Type Description
relativeHoursAfterAuthorisation integer/int32 The number of hours after the authorisation the settlement should take place.

ErrorReport

Report containing errors and warnings.

Name Type Description
language string/ELocale Locale in which the errors and warnings have been translated.
isFatalError boolean Indicates whether the errors and warnings lead up to a fatal error.
errors array[Entry] List of errors which occurred.
warnings array[Entry] List of warnings which occurred.

ErrorReportEntry

Error or warning entry for error report.

Name Type Description
code string The error or warning code.
message string The error or warning message.
translatedMessage string The translated error or warning message.
parameters array[string] The parameters.

HostedPage

Hosted page configuration.

Key Type Description
useCustomLogo boolean Indicates whether to use the custom logo.
customLogoReference string/int64 Unique reference to the custom logo image.
useCustomFavicon boolean Indicates whether to use the custom favicon.
customFaviconReference string/int64 Unique reference to the custom favicon image.
thumbnailReference string/int64 Unique reference to thumbnail image.
settings string General settings.
useCustomCss boolean Indicates whether to use the custom css.
customCss string Custom CSS to overwrite/extend the default CSS with.

Identity

An object containing information, additional to the address object, such as an email address, gender, and government numbers.

Name Type Description
debtorId string A reference, unique to the company, to the person this object relates to. This reference is supplied by the merchant.
emailAddress string Email address of the person this object relates to.
gender string/EGender The gender of the person this object relates to.
dateOfBirth string/date-time The date of birth of the person this object relates to.
socialSecurityNumber string A number, unique to the specified country, identifying the person this object relates to. This property can for example be used for a nine-digit Social Security number (SSN) for U.S citizens or a burgerservicenummer (BSN) for Dutch citizens.
chamberOfCommerceNumber string A number, unique to the chamber of commerce of the specified country, identifying the person, organization or company this object relates to.
vatNumber string A globally unique value added tax identification number of the person, organization or company this object relates to.

Image

Class that defines a image.

Key Type Description
data string/base64 Binary representation of the image
mimeType string Mime-type of the image
filename string Filename of the image

Invoice

An object relating to a sale transaction, indicating the products, quantities, and agreed prices for products or services the seller had provided the buyer.

Name Type Description
reference string A unique reference of this this.
invoiceNumber string The invoice number.
dateTimeUtc string/date-time The invoice date and time: date and time the invoice is made available to the customer. This may never be before the actual date that you make the this.
offline boolean Indicates whether or not the invoice is prepared and handled by an external system.
billingAddress Address The name, address and place of residence of the paying party.
billingIdentity Identity Additional details of the paying party. This contains for example the email address, social security number and/or vat number of the paying party.
shipmentTrackAndTraceInfo TrackAndTraceInfo The track and trace information for tracking the delivery of the goods specified in this this.
returnTrackAndTraceInfo TrackAndTraceInfo The track and trace information for tracking the return of the goods specified in this this.
totalInvoiceAmount string/decimal The total amount to be invoiced. Including VAT if VAT is specified for the payment job.
invoiceLines array[InvoiceLine] List of invoice lines that contain the invoice line details.

InvoiceLine

Part of an invoice that specify the order line details.

Name Type Description
lineNumber string/int64 A number, unique to an order, to determine the order of the order lines.
type string/EOrderLineType The type of product in this order line. For example "Discount" or "DigitalItem".
skuCode string A (unique) code that refers to a particular stock keeping unit.
name string The name of the product or service.
description string A description of the product or service.
quantity string/decimal The ordered quantity.
unitPriceExclVat string/decimal Unit price excluding value-added tax (VAT). Note: either one or both unit prices must be specified.
unitPriceInclVat string/decimal Unit price including value-added tax (VAT). Note: either one or both unit prices must be specified.
vatPercentage string/decimal Applied VAT percentage.
vatPercentageLabel string VAT percentage to display.
discountPercentageLabel string Discount percentage to display.
totalLineAmount string/decimal Total order line amount. Including VAT if the unit price including VAT is specified, otherwise excluding VAT.
url string A url that is shown in the portal to the receiver. This can be used to store a link to a product for easy navigation.
invoicedQuantity string/decimal The quantity of articles that are or have been invoiced.
totalInvoicedLineAmount string/decimal The total amount of this invoice line. Including VAT if VAT is specified for the payment job.

Issuer

An issuer, such as a bank.

Name Type Description
id string A unique identifier for an issuer. For example a bank identification code (BIC) in case of iDEAL.
name string Name of the issuer.

KeyJsonValuePair

A generic key/value pair.

Name Type Description
key string A key indicating the type of data contained in the value property.
value string The json data.

The predefined list of links that can be associated with a resource.

Name Type Description
data Link Where to find the resource.
action Link The (next) action location of the resource. Most commonly used to indicate a redirect for a payment action.
documentation Link Where to find documentation for the resource.

A single link to a supporting location.

Name Type Description
url string The location of the link.
type string The (mime)type of the link target.

Class that defines a logo.

Key Type Description
src string
src2x string

Mandate

The details of the authorization by a person, group, or organization (the mandator, in this case the debtor) to another (the mandatary, in this case the creditor) to allow the mandatary for making debt collections to the mandator.

Name Type Description
issueDate string/date-time The date this mandate was issued (and authorized).
revokeDate string/date-time The date this mandate was revoked. If null, the mandate has not been revoked.
paymentJobReference string/int64 Reference of the payment job used to verify the debtor.
paymentReference string/int64 Reference to the payment used to verify the debtor.
status string/EMandateStatus The status of this mandate.

MinMaxLimit

Used to define payment methods amount limits per currency.

Key Type Description
minimumCharge string/decimal Minimum charge for payment method to be valid for use
maximumCharge string/decimal Maximum charge for payment method to be valid for use

OAuthThirdPartyDetails

Name Type Description
merchantClientId string The client ID of the seller.
scopes array[string] An array of scopes that the seller granted the partner.

Order

An object containing information about ordered goods and services.

Name Type Description
orderNumber string The order number.
note string Additional comments or requests.
customerReference string/int64 A reference to the customer used for default billing address, billing identity and shipping address details.
createDateTimeUtc string Datetime the order was created.
billingAddress Address The name, address and place of residence of the paying party.
billingIdentity Identity Additional details of the paying party. This contains for example the email address, social security number and/or vat number of the paying party.
shippingAddress Address The name, address and place of residence of the party ultimately receiving the ordered goods or services.
orderLines array[OrderLine] List of order lines that that contain the order line details.

OrderLine

Part of an object that specify the order line details.

Name Type Description
lineNumber string/int64 A number, unique to an order, to determine the order of the order lines.
type string/EOrderLineType The type of product in this order line. For example "Discount" or "DigitalItem".
skuCode string A (unique) code that refers to a particular stock keeping unit.
name string The name of the product or service.
description string A description of the product or service.
quantity string/decimal The ordered quantity.
unitPriceExclVat string/decimal Unit price excluding value-added tax (VAT). Note: either one or both unit prices must be specified.
unitPriceInclVat string/decimal Unit price including value-added tax (VAT). Note: either one or both unit prices must be specified.
vatPercentage string/decimal Applied VAT percentage.
vatPercentageLabel string VAT percentage to display.
discountPercentageLabel string Discount percentage to display.
totalLineAmount string/decimal Total order line amount. Including VAT if the unit price including VAT is specified, otherwise excluding VAT.
url string A url that is shown in the portal to the receiver. This can be used to store a link to a product for easy navigation.

Outpayment

An object to allow for paying out to a third party.

Name Type Description
reference string/int64 A unique reference of this outpayment.
createDateTimeUtc string/date-time The date and time this outpayment has been created.
beneficiary OutpaymentBeneficiary The person to whom the outpayment is made. Outpayments with the same beneficiary, description and scheduled date and time are grouped together.
description string A description of this outpayment. This description is shown on the bank statement. Outpayments with the same beneficiary, description and scheduled date and time are grouped together.
scheduledDateTimeUtc string/date-time The date and time the outpayment is scheduled to get paid out. Outpayments with the same beneficiary, description and scheduled date and time are grouped together.
outPaidDateTimeUtc string/date-time The date and time this outpayment was paid out.
percentage string/decimal The percentage paid out in this outpayment, in relation to the split outpayment total.
amount string/decimal The amount to pay out in this outpayment.
status string/ESplitOutpaymentStatus The current status of this outpayment.
steps array[OutpaymentStep] A list of steps executed on this outpayment.

OutpaymentBeneficiary

The person who is paid.

Name Type Description
customerId string The id of the customer to which the transfer is made.
bic string Business Identifier Code (BIC) from the bank to which the transfer is made.
iban string International Bank Account Number (IBAN) to which the transfer is made.
nameOnBankAccount string Name of the owner of the bank account to which the transfer is made.

OutpaymentStep

A step that is performed on an outpayment.

Name Type Description
reference string/int64 A unique reference of this outpayment step.
createDateTimeUtc string/date-time The date and time this payment step has been created.
action string/EOutpaymentStepAction The action performed in this step.
status string/ESplitOutpaymentStatus The resulting status after performing the step's action.
description string A description describing the result of the performed action.

PageStatistics

Payment page statistics summary.

Name Type Description
pageId integer Unique identifier of the hosted payment page.
startedCount integer Total count of started payment jobs.
successCount integer Total succeeded payment jobs.
avgTimeToSuccessMs integer Average time until a payment job succeeded.
minTimeToSuccessMs integer Minimum time until a payment job succeeded.
maxTimeToSuccessMs integer Maximum time until a payment job succeeded.

Payment

An object to allow for paying someone or something.

Name Type Description
reference string/int64 A unique reference of this payment.
createDateTimeUtc string/date-time The date and time this payment has been created.
paymentMethods array[string/EPaymentMethod] List of the payment method(s) to use.This list will consist of multiple payment methods in case of a hosted payment, which are then reduced to exactly one payment method, during a payment. This is done by asking the payer to make a choice what payment method he wants to use.
status string/EPaymentStatus The current status of this payment.
lastErrorReport ErrorReport Last error report, containing the errors and warnings.
abuseReport AbuseReport The report from the abuse checks.
amountToCollect string/decimal The amount to collect in this payment in the currency specified in the payment job. If left empty the entire amountToCollect of the payment job is used upon start of the payment.
surchargeAmount string/decimal The amount which will be added to the originally supplied amount to collect.
convertedTotalAmount string/decimal The total amount to be paid in this payment in the currency compatible with the selected payment method. Equal to the amount to collect + surcharge amount, multiplied by the conversion rate. If null, the total amount has not been converted and the amount to collect + surcharge amount is used instead.
convertedCurrency string/ECurrency The currency to which the total amount is converted. If null, the total has not been converted and the currency specified in the payment job will then be used.
conversionRate string/decimal The conversion rate used for converting the total amount to the currency compatible with the selected payment method. If null, the amount to collect has not been converted.
paidAmount string/decimal The amount that the payer has has paid to the receiver. Only set after a payment is final (reversals such as chargebacks aside), for instance after a credit card capture.
steps array[PaymentStep] A list of steps executed on this payment.
flags Flags Flags that apply to this payment. They can either not be set or set with a true or false value.
attributes Attributes Attributes associated with this payment.
refunds array[Refund] List of refunds that are or will be executed on this payment.
captures array[Capture] List of captures that have been executed on this payment.

PaymentAttributes

All possible (public) payment attributes.

Name Type Description
OriginatingIpAddress string The IP address of the end-user interacting with the payment job.
OriginHeader string The origin header that might be usefull after returning from a 3rd party supplier.
UserAgent string The user agent of the browser of the end-user.
ReturnUrlSuccess string The definitive url the client web browser is redirected to in case of a success.
ReturnUrlFailed string The definitive url the client web browser is redirected to in case of a failure.
ReturnUrlCancelled string The definitive url the client web browser is redirected to in case of cancellation.
SimulatedStatus string The desired status of a simulated payment.
IdealBic string This is the bank selected for any iDEAL payment.
PaymentMethodTransactionId string Transaction id received from the payment method.
Token string Token to be used.
CashFlowsAcquiringDetails string JSON object with additional acquiring details if the payment is processed by CashFlows.

PaymentContract

The contract between a debtor and a creditor describing the details of the authorization of the creditor, by the debtor, to make debt collections.

Name Type Description
contractId string Merchant supplied identifier of this contract.
domain string The domain of the contract.
terminalId string The terminal id of the contract.
customerReference string/int64 A reference to the customer who is the owner and debtor in this contract and the mandator of the mandate. In most cases this will be the customer.
isB2B boolean Indicates whether the contract uses a B2B or Core scheme.
locale string/ELocale The language of the contract. This language will be used for sending reminders and so on.
amountToCollect string A fixed amount that will act as the default amount that will be collected, in every payment job. This amount is represented in the currency as specified in this contract. If null, the amount must be specified for each payment job individually.
currency string/ECurrency The currency in which the amount is specified in and in which the debt collections will be made. If null, the currency must be specified for each payment job individually.
schedule string A string describing the period of when a new debt collection will be made. If null, their debt collections will not be created periodically.
reminder Reminder The reminder to automatically send out to the debtor at a given date and time. If null, the reminder will not be sent out automatically.
expirationDate string/date-time The date and time after which the contract will expire. If null, the contract will not expire based on a date and time.
expirationCycles integer/int32 The number of cycles after which the contract will expire. If null, the contract will not expire based on a number of cycles.
activeMandate Mandate The currently active mandate. If null, no mandates are active.
invalidatedMandates array[Mandate] A list of mandates which can be used to prove the merchant was authorized to make a debt collection.
paymentJobReferences array[string/int64] A list of references to payment jobs that have been made based on this contract.
status string/EPaymentContractStatus The status of this contract indicating whether its an active contract or not.
traceReference string/int64 The trace reference of this contract, used for all actions executed on this contract.

PaymentFlags

All possible payment flags.

Name Type Description
NotificationPending boolean Flag to indicate that a notification still needs to be sent to the terminal.

PaymentJob

A payment job.

Name Type Description
reference string/int64 A unique reference of this payment job.
createDateTimeUtc string/date-time The date and time this payment job has been created.
type string/EPaymentType The type of payments of this payment job.
traceReference string/int64 A reference to a trace object which will trace all actions executed on this payment.
terminalId string The id of the site or service the payment job is associated with.
domain string The domain where the request arrived on.
terminalMetaData string Additional data attached to this object, set on creation, exclusively for use by the terminal. Maximum 1k in size.
locale string/ELocale Language (culture and subculture, RFC 4646) in which the hosted page, and info and error messages are shown.
order Order The order where the payment job is executed on.
parentPaymentJobReference string/int64 A reference to the parent payment job.
paymentMethodsToUse array[string/EPaymentMethod] A list of payment methods to enable for this request. If none are supplied, all configured and applicable payment methods will be used.
displayUrl string A URL that is shown in the portal to the receiver. This can be used to store a link to an order in the receiver's order system for easy navigation.
currency string/ECurrency The currency in which the amount to collect, surcharge amount and paid amount are specified and what will be used as the preferred currency by the payment method(s).
amountToCollect string/decimal The amount to collect in this payment job.
amountCollected string/decimal The amount collected in this payment job so far. Only set after a payment is final (reversals such as chargebacks aside), for instance after a credit card capture.
paidAmount string/decimal The amount that the payer has has paid, which includes surcharge amounts. Only set after a payment is final (reversals such as chargebacks aside), for instance after a credit card capture.
paidDateTimeUtc string/date-time The date and time the total to amount to collect has been paid. Null if the payment job is not fully paid.
expirationDateTimeUtc string/date-time The date and time the payment job expires and is no longer valid.
DueDateTimeUtc string/date-time The date and time the payment job needs processing.
LastSeenTimeUtc string/date-time The date and time the payment job was viewed on the paymentpage.
LastProcessedTimeUtc string/date-time The date and time the payment job was last processed.
flags Flags Flags that apply to this payment job. They can either not be set or set with a true or false value.
attributes Attributes Attributes associated with this payment job.
paymentStatus string/EPaymentStatus The current summary status of all payments.
reversalStatus string/EReversalStatus The current summary status of all reversals.
payments array[Payment] List of payments that are part of this payment job.
invoices array[Invoice] List of invoices that are part of this payment job.
reversals array[Reversal] List of reversals that are executed within this payment job.
splitOutpayment SplitOutpayment Details on how this payment job funds are distributed to multiple recipients. If null, outpayments will not be split.

PaymentJobAttributes

All possible (public) payment job attributes.

Name Type Description
WebhookUrl string The URL that is called whenever there are noteworthy payment job related status updates. Note that we're not sending the actual status with this call. It's up to the receiving party to manually call our APIs to get the latest status.
GoogleAnalyticsClientId string The content of the _ga cookie which is equal to the google analytics client id.

PaymentJobFlags

All possible payment job flags.

Name Type Description
SecondChanceEmailSent Boolean Flag to indicate if a second chance email has been sent to the payee.
PaidBySecondChanceEmail Boolean Flag to indicate if a payment job has been (partially) paid using the link provided in the sent second chance email.
Moto Boolean Mail or telephone order.
RecurringParent Boolean Parent payment for recurring payments (subscriptions and the like).
Direct Boolean This flag is set when the payment processor receives all the required payment data on the first attempt (bypassing our payment pages). For example; this happens when an acquiring credit card payment is created.

PaymentJobParameters

All possible payment job parameters. These parameters are solely used to steer payments, refunds and other payment job related flows. They are not stored in the payment job.

Name Type Description
OriginatingIpAddress string The IP address of the end-user interacting with the payment job.
OriginHeader string The origin header that might be usefull after returning from a 3rd party supplier.
UserAgent string The user agent of the browser of the end-user.
ReturnUrlSuccess string The url the client web browser is redirect to in case of a success. If not set the configured url from the configuration is used. If no url is configured a default success page will be shown.
ReturnUrlFailed string The url the client web browser is redirect to in case of non success (expired and failed). If not set the configured url from the configuration is used. If nothing is configured a default failed page will be shown.
ReturnUrlCancelled string The url the client web browser is redirect to in case of a cancel (expired,cancelled,failed etc.). If not set the configured url from the configuration is used. If nothing is configured a default failed page will be shown.
WebhookUrl string The url that is called whenever there are noteworthy payment job related status updates. Note that we're not sending the actual status with this call. It's up to the receiving party to manually call our APIs to get the latest status.
PaymentPageId string The supplied (integer) page id that will be used for showing a payment page this will override the page id selection mechanism used in the campaign API and will influence campaign results
SimulatedStatus string The simulated status.
IdealBic string This is the bank selected for any iDEAL payment.
SelectedPaymentMethod string The selected payment method on the hosted pages.
CardHolder string Card holder information.
CardNumber string Number on credit card.
CardCvc string Card verification code.
CardExpiryMonth string Expiry month of credit card.
CardExpiryYear string Expiry year of credit card.
PaRes string 3D-Secure payer authentication response.
Md string 3D-Secure merchant data.
Token string Token provided by payment facilitator, initially used for PayPal.
PayerId string Payer Id provided by payment facilitator, initially used for PayPal.
GoogleAnalyticsClientId string The content of the _ga cookie which is equal to the google analytics client id.

PaymentMethodInfo

Object containing details about a payment method.

Name Type Description
paymentMethod string/EPaymentMethod The payment method.
logo Logo The logo of the payment method.
issuerList array[Issuer] List of supported issuers for this payment method.
supportsTokenization boolean true if method supports tokenization
tokenizedCreditCards array[TokenizedCreditCard] List of tokenized credit cards
currencies array[string/ECurrency] Supported currencies for this payment method.
surchargeAmount string/decimal Amount on top of the amount to collect, for the use of this payment method, including value-added tax.
surchargeAmountExclVat string/decimal Amount on top of the amount to collect, for the use of this payment method, excluding value-added tax.
surchargeAmountVat string/decimal The amount of value-added tax in the surcharge amount.
surchargeVatPercentage string/decimal The surcharge vat percentage.
description string A description about this payment method.

PaymentMethodState

Object containing payment method with their enable/disabled state.

Key Type Description
paymentMethod string/EPaymentMethod The payment method
enabled boolean Enabled or disabled state of the payment method

PaymentStep

A step that is performed on a payment.

Name Type Description
reference string/int64 A unique reference of this payment step.
createDateTimeUtc string/date-time The date and time this payment step has been created.
action string/EPaymentStepAction The action performed in this step.
paymentMethods array[string/EPaymentMethod] List of the payment method(s) to use. This list will consist of multiple payment methods in case of a hosted payment, which are then reduced to exactly one payment method, during a payment. This is done by asking the payer to make a choice in what payment method he wants to use.
status string/EPaymentStatus The resulting status after performing the step's action.
amountToCollect string/decimal The amount to collect in this payment in the currency specified in the payment job.

PayPal

Configuration of PayPal

Name Type Description
merchantId string The merchant id of the seller account linked with the CashFlows account at PayPal.
autoCapture bool Set this property to true to automatically and immediately capture a payment after authorization.
oAuthThirdPartyDetails OAuthThirdPartyDetails OAuth details of the contract between the seller (the merchant) and the partner (us).
paymentsReceivable bool Indicates whether the seller account can receive payments.
contractStatus string/EContractStatus The contract status of this payment method.
currencySettings CurrenciesSettings Individual settings per currency.
dynamicSettlementTiming DynamicSettlementTimings Dynamic settlement timing settings.
enableAbuseChecks bool Indicates whether abuse checks should be executed for this payment type.
abuseScoreBlockThreshold string/decimal The score (0-100) at which a payment should be rejected.

PortalConfig

The class that defines portal config.

Name Type Description
configuration string A string with configuration.

Refund

An object to allow for refunding money, typically to a customer who is not satisfied with goods or services bought.

Name Type Description
reference string/int64 A unique reference of this refund.
createDateTimeUtc string/date-time The date and time this refund has been created.
creditNumber string A merchant supplied reference to this refund.
creditNote string Additional comment or request.
status string/ERefundStatus The current status of the refund.
amountToRefund string/decimal The amount to refund in the currency specified in the payment job.
convertedAmountToRefund string/decimal The amount to refund in the currency compatible with the selected method. Equal to the amount to refund multiplied by the conversion rate. If null, the amount to refund has not been converted and the amount to refund is used instead.
convertedCurrency string/ECurrency The currency to which the amount to refund is converted to and in which the converted amount to refund is specified in. If null, the amount to refund has not been converted. The currency specified in the payment job will then be used.
conversionRate string/decimal The conversion rate used for converting the amount to refund to the currency compatible with the selected method. This rate multiplied by the amount to refund results in the converted amount to refund. If null, the amount to refund has not been converted.
paymentReference string/int64 Reference to the payment if a payment is refunded.
steps array[RefundStep] A list of steps executed on this refund.

RefundStep

A step that is performed on a refund.

Name Type Description
reference string/int64 A unique reference of this refund step.
createDateTimeUtc string/date-time The date and time this refund step has been created.
action string/ERefundStepAction The action performed in this step.
status string/ERefundStatus The resulting status after performing the step's action.
description string A description of the result of the performed action.
resultAttributes RefundStepResultAttributes List of attributes generated by the refund method, like references, reliability scores etc.

RefundStepResultAttributes

Attributes generated by the refund method

Name Type Description

Reminder

Details of when to send a reminder of a future debt collection to the debtor.

Name Type Description
daysBefore integer/int32 The number of days before the debt collection will take place to send the reminder to the debtor.
timeOfDay string/date-time The time at when the reminder should be send to the debtor.

Reversal

An object to allow for the reversal of a payment. Usually, such a request is the result of a suspected unauthorized payment made or insufficient funds.

Name Type Description
reference string/int64 A unique reference of this reversal.
dateTimeUtc string/date-time The date and time the reversal has been processed.
reversedAmount string/decimal The reversed amount in the currency specified in the currency property.
currency string/ECurrency The currency in which the reversed amount is specified.
paymentReference string/int64 Reference to the payment that is reversed.
originatingPaymentMethod string/PaymentMethod The payment method of the payment that is reversed.
description string A description of the reversal.
resultAttributes ReversalResultAttributes List of attributes, like references, reliability scores etc.

ReversalResultAttributes

Attributes generated by the reversal.

Name Type Description

SplitOutpayment

An object to allow for splitting outpayments to different parties.

Name Type Description
createDateTimeUtc string/date-time The date and time this split outpayment has been created.
percentageCollected string/decimal Percentage used for collection
amountToSplit string/decimal The total amount to split in this split outpayment. This is equal to the paid amount in the payment job.
amountForMerchant string/decimal The amount to pay out to the merchant.
amountAvailableForOutpayment string/decimal The amount available for paying out to third parties.
amountScheduled string/decimal The amount scheduled to pay out to third parties.
amountOutpaid string/decimal The amount that has been paid out to the merchant and all third parties. This amount will ultimately be equal to the amount to split.
outpayments array[Outpayment] List of outpayments that are part of this split outpayment.

Surcharge

Key Type Description
fixedAmount string/decimal A fixed amount to charge (can be combined with percentage if required)
minimumAmount string/decimal The minimum amount (inclusive VAT) to charge, if null or zero no minimum amount applies
percentage string/decimal The percentage used for calculating surcharge (exclusive VAT), when null or zero no percentage is added
vatPercentage string/decimal The VAT percentage that will be added to the calculated surcharge

Terminal

Terminal settings.

Name Type Description
version integer Indicates the version of this config, each update will update the version number. At insert version can be omitted.
terminalId string The terminal id assigned by CashFlows.
businessId string The business id assigned by CashFlows.
merchantId string The merchant id assigned by CashFlows.
contractStatus string/EContractStatus The contract status of this terminal.
tradeName string Trade name that will be shown where this is usefull, for example in the hosted page.
description string Description for the terminal configuration, editable by the profile.
primaryPassword string Password used to sign messages, if secondary password is null for this profile. This is also used to verify incoming messages.
secondaryPassword string If set this password is used to sign messages. Also used to verify incoming messages if primary password fails verification. Password change procedure: You first generate a new secondary password and if all clients are updated and using this new password you move the secondary password to the primary password and remove the secondary password.
defaultPageId integer One can configure another pageId as the default 0. (if other id's are created and can be selected).
isSandbox boolean Indicates if this terminal configuration is used for sandbox environment.
switches TerminalSwitch Configured switches.
parameters TerminalParameter Configured parameters.
paymentMethods array[PaymentMethodState] List of the payment method(s) to use. The order of paymentmethods indicate the order on which they appear on the hosted page.

TerminalParameter

Terminal parameters.

Value Type Description
GoogleAnalytics Name string The value for the google analytics Name(format is validated)
DefaultReturnUrlSuccess string default url for succesfull paymentjobs
DefaultReturnUrlCancelled string default url for cancelled paymentjobs
DefaultReturnUrlFailed string default url for failed paymentjobs
SystemNotificationsEmail string email address for system notifications (technical contact)
DefaultWebhookUrl string default webhook url, when not overriden.
SecondChanceEmailWaitTimeMinutes string Wait time in minutes before second chance email is sent after last activity

TerminalSwitch

Terminal switches.

Name Type Description
SecondChanceEmailEnabled boolean Enable second chance email handling

TokenizedCreditCard

Name Type Description
version integer Indicates the version of this config, each update will update the version number. At insert version can be omitted.
cardExpiryMonth string Expiry month range "01-12"
cardExpiryYear string Expiry year 2 digit year range "01-99"
truncatedCardNumber string The truncated creditcard number

Trace

A trace.

Name Type Description
reference string/long The reference of this trace.
traceSequences array[TraceSequence] A list of trace sequences that are bound to this tracereference.

TraceSequence

An object containing track and trace information which can be used to determine current and past locations (and other information) of the shipment this object is linked to.

Name Type Description
sequence string/long The sequence of this report.
timestampUtc string/date-time The timestamp this sequence was recorded.
machineName string The machine this sequence was generated/detected on.
state string The state of this sequence (if specified).
traceString string The trace of this sequence.
comment string An optional comment on this trace sequence.
fromEndpoint string The endpoint the sequence originated from.
toEndpoint string The endpoint the squence was targetted at.
success boolean The result of this trace sequence.
isPrivate boolean When isPrivate is true this sequence should only be shown if display is for CashFlows service personel
diagnostic string Additional diagnostic data for the trace. This property is stored alongside the trace, which allows for more efficient filtering abilities. The most common use case would be to monitor detached traces, such as traces that aren't linked to a payment job.
ipAddress string Specify the ip address if this is relevant for the trace. Typical the ip address is saved when a request is received on the ingres side of the gateway.

TrackAndTraceInfo

An object containing track and trace information which can be used to determine current and past locations (and other information) of the shipment this object is linked to.

Name Type Description
trackingNumber string A reference, unique to the distributer, of this track and trace object.
trackingUrl string An URL pointing to a resource where the current and past locations (and other information) of the shipment this track and trace info is linked to can be found.
shippingCompany string The name of the shipping company.
shippingMethod string The shipping method used.

UserInfo

An object containing user information.

Name Type Description
userId string The id of the user.
email string The email of the user.
firstName string The first name of the user.
lastName string The last name of the user.
roles array[string] The roles assigned to the user.

Enumerations

ECaptureStatus

Capture status

Value Description
Pending A capture is pending
Completed A capture has succeeded
Failed A capture has failed

EConfigParameter

Config parameters

Value Description
GoogleAnalytics Name The value for the google analytics Name(format is validated)
DefaultReturnUrlSuccess default url for succesfull paymentjobs
DefaultReturnUrlCancelled default url for cancelled paymentjobs
DefaultReturnUrlFailed default url for failed paymentjobs
SystemNotificationsEmail email address for system notifications (technical contact)
DefaultWebhookUrl default webhook url, when not overriden.
SecondChanceEmailWaitTimeMinutes Wait time in minutes before second chance email is sent after last activity

EConfigSwitch

Config switches

Name Description
SecondChanceEmailEnabled Enable second chance email handling

EContractStatus

Contract statuses

Value Description
Unknown
ReviewRequested
UnderReview
Granted
Rejected

ECountry

Country in ISO 3166-1 alpha-2: two-letter country code.

Value Description
AF Afghanistan
AX Åland Islands
AL Albania
DZ Algeria
AS American Samoa
AD Andorra
AO Angola
AI Anguilla
AQ Antarctica
AG Antigua and Barbuda
AR Argentina
AM Armenia
AW Aruba
AU Australia
AT Austria
AZ Azerbaijan
BS Bahamas (the)
BH Bahrain
BD Bangladesh
BB Barbados
BY Belarus
BE Belgium
BZ Belize
BJ Benin
BM Bermuda
BT Bhutan
BO Bolivia (Plurinational State of)
BQ Bonaire Sint Eustatius Saba
BA Bosnia and Herzegovina
BW Botswana
BV Bouvet Island
BR Brazil
IO British Indian Ocean Territory (the)
BN Brunei Darussalam
BG Bulgaria
BF Burkina Faso
BI Burundi
CV Cabo Verde
KH Cambodia
CM Cameroon
CA Canada
KY Cayman Islands (the)
CF Central African Republic (the)
TD Chad
CL Chile
CN China
CX Christmas Island
CC Cocos (Keeling) Islands (the)
CO Colombia
KM Comoros (the)
CD Congo (the Democratic Republic of the)
CG Congo (the)
CK Cook Islands (the)
CR Costa Rica
CI Côte d'Ivoire [h]
HR Croatia
CU Cuba
CW Curaçao
CY Cyprus
CZ Czechia
DK Denmark
DJ Djibouti
DM Dominica
DO Dominican Republic (the)
EC Ecuador
EG Egypt
SV El Salvador
GQ Equatorial Guinea
ER Eritrea
EE Estonia
SZ Eswatini
ET Ethiopia
FK Falkland Islands (the)
FO Faroe Islands (the)
FJ Fiji
FI Finland
FR France
GF French Guiana
PF French Polynesia
TF French Southern Territories (the)
GA Gabon
GM Gambia (the)
GE Georgia
DE Germany
GH Ghana
GI Gibraltar
GR Greece
GL Greenland
GD Grenada
GP Guadeloupe
GU Guam
GT Guatemala
GG Guernsey
GN Guinea
GW Guinea-Bissau
GY Guyana
HT Haiti
HM Heard Island and McDonald Islands
VA Holy See (the)
HN Honduras
HK Hong Kong
HU Hungary
IS Iceland
IN India
ID Indonesia
IR Iran (Islamic Republic of)
IQ Iraq
IE Ireland
IM Isle of Man
IL Israel
IT Italy
JM Jamaica
JP Japan
JE Jersey
JO Jordan
KZ Kazakhstan
KE Kenya
KI Kiribati
KP Korea (the Democratic People's Republic of)
KR Korea (the Republic of)
KW Kuwait
KG Kyrgyzstan
LA Lao People's Democratic Republic (the)
LV Latvia
LB Lebanon
LS Lesotho
LR Liberia
LY Libya
LI Liechtenstein
LT Lithuania
LU Luxembourg
MO Macao
MK Macedonia (the former Yugoslav Republic of)
MG Madagascar
MW Malawi
MY Malaysia
MV Maldives
ML Mali
MT Malta
MH Marshall Islands (the)
MQ Martinique
MR Mauritania
MU Mauritius
YT Mayotte
MX Mexico
FM Micronesia (Federated States of)
MD Moldova (the Republic of)
MC Monaco
MN Mongolia
ME Montenegro
MS Montserrat
MA Morocco
MZ Mozambique
MM Myanmar
NA Namibia
NR Nauru
NP Nepal
NL Netherlands (the)
NC New Caledonia
NZ New Zealand
NI Nicaragua
NE Niger (the)
NG Nigeria
NU Niue
NF Norfolk Island
MP Northern Mariana Islands (the)
NO Norway
OM Oman
PK Pakistan
PW Palau
PS Palestine, State of
PA Panama
PG Papua New Guinea
PY Paraguay
PE Peru
PH Philippines (the)
PN Pitcairn
PL Poland
PT Portugal
PR Puerto Rico
QA Qatar
RE Réunion
RO Romania
RU Russian Federation (the)
RW Rwanda
BL Saint Barthélemy
SH Saint Helena, Ascension and Tristan da Cunha
KN Saint Kitts and Nevis
LC Saint Lucia
MF Saint Martin (French part)
PM Saint Pierre and Miquelon
VC Saint Vincent and the Grenadines
WS Samoa
SM San Marino
ST Sao Tome and Principe
SA Saudi Arabia
SN Senegal
RS Serbia
SC Seychelles
SL Sierra Leone
SG Singapore
SX Sint Maarten (Dutch part)
SK Slovakia
SI Slovenia
SB Solomon Islands
SO Somalia
ZA South Africa
GS South Georgia and the South Sandwich Islands
SS South Sudan
ES Spain
LK Sri Lanka
SD Sudan (the)
SR Suriname
SJ Svalbard Jan Mayen
SE Sweden
CH Switzerland
SY Syrian Arab Republic
TW Taiwan (Province of China)
TJ Tajikistan
TZ Tanzania, United Republic of
TH Thailand
TL Timor-Leste
TG Togo
TK Tokelau
TO Tonga
TT Trinidad and Tobago
TN Tunisia
TR TurName
TM Turkmenistan
TC Turks and Caicos Islands (the)
TV Tuvalu
UG Uganda
UA Ukraine
AE United Arab Emirates (the)
GB United Kingdom of Great Britain and Northern Ireland (the)
UM United States Minor Outlying Islands (the)
US United States of America (the)
UY Uruguay
UZ Uzbekistan
VU Vanuatu
VE Venezuela (Bolivarian Republic of)
VN Viet Nam
VG Virgin Islands (British)
VI Virgin Islands (U.S.)
WF Wallis and Futuna
EH Western Sahara
YE Yemen
ZM Zambia
ZW Zimbabwe

ECurrency

Currency in ISO-4217.

Value Description
AED United Arab Emirates dirham
AFN Afghan afghani
ALL Albanian lek
AMD Armenian dram
ANG Netherlands Antillean guilder
AOA Angolan kwanza
ARS Argentine peso
AUD Australian dollar
AWG Aruban florin
AZN Azerbaijani manat
BAM Bosnia and Herzegovina convertible mark
BBD Barbados dollar
BDT Bangladeshi taka
BGN Bulgarian lev
BHD Bahraini dinar
BIF Burundian franc
BMD Bermudian dollar
BND Brunei dollar
BOB Boliviano
BOV Bolivian Mvdol (funds code)
BRL Brazilian real
BSD Bahamian dollar
BTN Bhutanese ngultrum
BWP Botswana pula
BYN Belarusian ruble
BZD Belize dollar
CAD Canadian dollar
CDF Congolese franc
CHE WIR Euro (complementary currency)
CHF Swiss franc
CHW WIR Franc (complementary currency)
CLF Unidad de Fomento (funds code)
CLP Chilean peso
CNY Renminbi (Chinese) yuan
COP Colombian peso
COU Unidad de Valor Real (UVR) (funds code)
CRC Costa Rican colon
CUC Cuban convertible peso
CUP Cuban peso
CVE Cape Verde escudo
CZK Czech koruna
DJF Djiboutian franc
DKK Danish krone
DOP Dominican peso
DZD Algerian dinar
EGP Egyptian pound
ERN Eritrean nakfa
ETB Ethiopian birr
EUR Euro
FJD Fiji dollar
FKP Falkland Islands pound
GBP Pound sterling
GEL Georgian lari
GHS Ghanaian cedi
GIP Gibraltar pound
GMD Gambian dalasi
GNF Guinean franc
GTQ Guatemalan quetzal
GYD Guyanese dollar
HKD Hong Kong dollar
HNL Honduran lempira
HRK Croatian kuna
HTG Haitian gourde
HUF Hungarian forint
IDR Indonesian rupiah
ILS Israeli new shekel
INR Indian rupee
IQD Iraqi dinar
IRR Iranian rial
ISK Icelandic króna
JMD Jamaican dollar
JOD Jordanian dinar
JPY Japanese yen
KES Kenyan shilling
KGS Kyrgyzstani som>
KHR Cambodian riel
KMF Comoro franc
KPW North Korean won
KRW South Korean won
KWD Kuwaiti dinar
KYD Cayman Islands dollar
KZT Kazakhstani tenge
LAK Lao kip
LBP Lebanese pound
LKR Sri Lankan rupee
LRD Liberian dollar
LSL Lesotho loti
LYD Libyan dinar
MAD Moroccan dirham
MDL Moldovan leu
MGA Malagasy ariary
MKD Macedonian denar
MMK Myanmar kyat
MNT Mongolian tögrög
MOP Macanese pataca
MRU Mauritanian ouguiya
MUR Mauritian rupee
MVR Maldivian rufiyaa
MWK Malawian kwacha
MXN Mexican peso
MXV Mexican Unidad de Inversion (UDI) (funds code)
MYR Malaysian ringgit
MZN Mozambican metical
NAD Namibian dollar
NGN Nigerian naira
NIO Nicaraguan córdoba
NOK Norwegian krone
NPR Nepalese rupee
NZD New Zealand dollar
OMR Omani rial
PAB Panamanian balboa
PEN Peruvian sol
PGK Papua New Guinean kina
PHP Philippine peso
PKR Pakistani rupee
PLN Polish złoty
PYG Paraguayan guaraní
QAR Qatari riyal
RON Romanian leu
RSD Serbian dinar
RUB Russian ruble
RWF Rwandan franc
SAR Saudi riyal
SBD Solomon Islands dollar
SCR Seychelles rupee
SDG Sudanese pound
SEK Swedish krona/kronor
SGD Singapore dollar
SHP Saint Helena pound
SLL Sierra Leonean leone
SOS Somali shilling
SRD Surinamese dollar
SSP South Sudanese pound
STN São Tomé and Príncipe dobra
SVC Salvadoran colón
SYP Syrian pound
SZL Swazi lilangeni
THB Thai baht
TJS Tajikistani somoni
TMT Turkmenistan manat
TND Tunisian dinar
TOP Tongan paʻanga
TRY Turkish lira
TTD Trinidad and Tobago dollar
TWD New Taiwan dollar
TZS Tanzanian shilling
UAH Ukrainian hryvnia
UGX Ugandan shilling
USD United States dollar
USN United States dollar (next day) (funds code)
UYI Uruguay Peso en Unidades Indexadas (URUIURUI) (funds code)
UYU Uruguayan peso
UYW Unidad previsional
UZS Uzbekistan som
VES Venezuelan bolívar soberano
VND Vietnamese đồng
VUV Vanuatu vatu
WST Samoan tala
XAF CFA franc BEAC
XAG Silver (one troy ounce)
XAU Gold (one troy ounce)
XBA European Composite Unit (EURCO) (bond market unit)
XBB European Monetary Unit (E.M.U.-6) (bond market unit)
XBC European Unit of Account 9 (E.U.A.-9) (bond market unit)
XBD European Unit of Account 17 (E.U.A.-17) (bond market unit)
XCD East Caribbean dollar
XDR Special drawing rights
XOF CFA franc BCEAO
XPD Palladium (one troy ounce)
XPF CFP franc (franc Pacifique)
XPT Platinum (one troy ounce)
XSU SUCRE
XTS Code reserved for testing purposes
XUA ADB Unit of Account
XXX No currency
YER Yemeni rial
ZAR South African rand
ZMW Zambian kwacha

EFileType

Value Description
csv
xlsx
pdf

EGender

Value Description
Female
Male

EGrantType

Value Description
AuthorizationCode The authorization code grant type obtained after login.
RefreshToken The refresh token grant type obtained when creating an access token.

ELocale

The Locale enum specifies a unique entry for each supported culture, based on RFC 4646. The name is a combination of an ISO 639 two-letter lowercase (ISO 639-1) culture code associated with a language and an ISO 3166 two-letter uppercase (ISO 3166-1 alpha-2) subculture code associated with country or region.

Value Description
nl_NL Dutch, Flemish / Netherlands
nl_BE Dutch, Flemish / Belgium
de_DE German / Germany
en_US English / United States of America
en_GB English / Great Britain

EMandateStatus

Indicates the status of a mandate.

Value Description
Pending Indicates the mandate is pending or waiting for approval.
Active Indicates the mandate is active.
RevokedByBank Indicates the mandate was cancelled by the bank.
RevokedByDebtor Indicates the mandate was cancelled by the debtor.
RevokedByCreditor Indicates the mandate was cancelled by the creditor.

EOrderLineType

The type of order line.

Value Description
PhysicalItem An order line specifying a physical item.
DigitalItem An order line specifying a digital item.
ShippingCost An order line specifying the shipping costs.
PaymentCost An order line specifying the payment costs (the surcharges).
Discount An order line specifying the amount added to the total amount, because of a discount.
GiftCard An order line specifying the amount added to the total amount, because it's paid with a gift card.
ShopCredit An order line specifying the amount added to the total amount, because it's paid with shop credit.

EOutpaymentStepAction

Value Description

EPaymentAttribute

The enumeration of all possible (public) payment attributes.

Value Description
OriginatingIpAddress The IP address of the end-user interacting with the payment job.
OriginHeader The origin header that might be usefull after returning from a 3rd party supplier.
UserAgent The user agent of the browser of the end-user.
ReturnUrlSuccess The definitive url the client web browser is redirected to in case of a success.
ReturnUrlFailed The definitive url the client web browser is redirected to in case of a failure.
ReturnUrlCancelled The definitive url the client web browser is redirected to in case of cancellation.
SimulatedStatus The desired status of a simulated payment.
IdealBic This is the bank selected for any iDEAL payment
PaymentMethodTransactionId Transaction id received from the payment method.
Token Token to be used.
CashFlowsAcquiringDetails JSON object with additional acquiring details if the payment is processed by CashFlows.

EPaymentFlag

Type of payment flag.

Value Description
NotificationPending Flag to indicate that a notification still needs to be sent to the terminal.

EPaymentContractStatus

Indicates the status of a payment contract.

Value Description
Pending Indicates the payment contract is pending or waiting for approval.
Active Indicates the payment contract is active.
Paused Indicates the payment contract is paused: (temporarily) inactive.
Expired Indicates the contract has expired.
Broken Indicates the contract has been broken.

EPaymentJobAttribute

The enumeration of all possible (public) payment job attributes.

Value Description
WebhookUrl The URL that is called whenever there are noteworthy payment job related status updates. Note that we're not sending the actual status with this call. It's up to the receiving party to manually call our APIs to get the latest status.
GoogleAnalyticsClientId The content of the _ga cookie which is equal to the google analytics client id.

EPaymentJobFlag

Type of payment job flag.

Value Description
SecondChanceEmailSent Flag to indicate if a second chance email has been sent to the payee.
PaidBySecondChanceEmail Flag to indicate if a payment job has been (partially) paid using the link provided in the sent second chance email.
Moto Mail or telephone order.
RecurringParent Parent payment for recurring payments (subscriptions and the like).
Direct This flag is set when the payment processor receives all the required payment data on the first attempt (bypassing our payment pages). For example; this happens when an acquiring credit card payment is created.

EPaymentJobOption

The enumeration of all possible payment job options.

Value Description
IsRecurringPaymentJobParent Marks the payment job as parent for a recurring payment job.
IsMoto Marks the payment job as a moto payment job.
StoreCustomerInformation Store the customer information for re-use.
GenerateToken Tokens are unique references to payment data, such as creditcard details. A token can be used to initiate a payment without having to provide these sensitive data.

EPaymentJobParameter

The enumeration of all possible payment job parameters. These parameters are solely used to steer payments, refunds and other payment job related flows. They are not stored in the payment job.

Value Description
OriginatingIpAddress The IP address of the end-user interacting with the payment job.
OriginHeader The origin header that might be usefull after returning from a 3rd party supplier.
UserAgent The user agent of the browser of the end-user.
ReturnUrlSuccess The url the client web browser is redirect to in case of a success. If not set the configured url from the configuration is used. If no url is configured a default success page will be shown.
ReturnUrlFailed The url the client web browser is redirect to in case of non success (expired and failed). If not set the configured url from the configuration is used. If nothing is configured a default failed page will be shown.
ReturnUrlCancelled The url the client web browser is redirect to in case of a cancel (expired,cancelled,failed etc.). If not set the configured url from the configuration is used. If nothing is configured a default failed page will be shown.
WebhookUrl The url that is called whenever there are noteworthy payment job related status updates. Note that we're not sending the actual status with this call. It's up to the receiving party to manually call our APIs to get the latest status.
PaymentPageId The supplied (integer) page id that will be used for showing a payment page this will override the page id selection mechanism used in the campaign API and will influence campaign results
SimulatedStatus The simulated status.
IdealBic This is the bank selected for any iDEAL payment.
SelectedPaymentMethod The selected payment method on the hosted pages.
CardHolder Card holder information.
CardNumber Number on credit card.
CardCvc Card verification code.
CardExpiryMonth Expiry month of credit card.
CardExpiryYear Expiry year of credit card.
PaRes 3D-Secure payer authentication response.
Md 3D-Secure merchant data.
Token Token provided by payment facilitator, initially used for PayPal.
PayerId Payer Id provided by payment facilitator, initially used for PayPal.
GoogleAnalyticsClientId The content of the _ga cookie which is equal to the google analytics client id.

EPaymentMethod

Value Description
Creditcard
PayPal

EPaymentStatus

The various possible payment statuses.

Value Description
Pending
Reserved
Commissioned
Paid
Cancelled
Failed
Rejected
Expired

EPaymentStepAction

Value Description
DisplayHostedPage
PaymentMethodSelection
Start
Process
BackgroundProcess
Capture
Refund
Cancel

EPaymentType

The type of payment.

Value Description
Payment Indicates payment from customer to merchant.
Credit Indicates payment from merchant to customer.

EPhoneNumberType

Type of phone number.

Value Description
Unknown The type of phone number is not known.
Mobile Mobile phone number.
Fixed Fixed/landline number.

ERefundStatus

The various possible refund statuses.

Value Description
Pending
Completed
Failed

ERefundStepAction

Value Description
Start
Process
Cancel

EReportType

Value Description
RemittanceStatement
TradingStatement
CostsStatement
ReservesStatement
SecurityStatement
SettlementBatchReport
TransactionReport

EReversalStatus

Value Description
NotReversed
PartiallyReversed
Reversed

ESplitOutpaymentStatus

Value Description
Created
InProgress
Completed
Failed
Show examples in:
Payment Gateway API Documentation