Integrate Credit card

This is the guide for integrating Credit card only. For a general overview of integrating Pats and to get to know the redirection flow of a transaction, please see the checkout integration page. For an overview of payment method specific transaction details please take a look the transaction details page.

Transaction lifecycle

The Credit card transaction progresses through a number of states:

Possible states for Credit card:

• INITIATED — The transaction has been successfully created in our system, but hasn't been processed yet.
• IN_PROGRESS — The consumer is busy with the payment.
• AUTHORIZED — The transaction has been authorized by the customer, and can now be processed. One can now void or capture the authorization.
• AUTHORIZATION_VOIDED — The transaction has been cancelled by you, prior to being queued for processing.
• PENDING — The transaction is being processed, and a final status has not yet been assigned.
• SETTLEMENT_REQUESTED — The transaction has been queued for processing. This request can be cancelled.
• SETTLEMENT_COMPLETED — The transaction has been successfully processed. The transaction can now be refunded.
• CANCELLED — The transaction has been cancelled by the customer.
• DECLINED — The transaction request has been declined by the payment processor.
• FAILED — The transaction has been rejected by us, or an error has occurred during transaction processing, most likely because the transaction request is malformed or inconsistent.
• UNKNOWN — A critical state meaning that something has gone seriously wrong. The transaction's state cannot be determined at the present time.
• ABANDONED — The transaction has been abandoned by the customer.

Create new customer

Before initiating the transaction you have to create a customer object and add the id to the transaction. For returning customers you don't have to create a new customer object.

You can create a customer object by making a POST request to the following url.

/v1/customer

For instance, here is a valid request body:

{
    "title": "ms",
    "gender": "female",
    "initials": "J",
    "first_name": "Jaimy",
    "last_name": "Uil",
    "date_of_birth": "1971-05-12",
    "street_address": "Korte nieuwstraat",
    "house_number": "5846",
    "city": "Naarden",
    "region": "Zuid-holland",
    "postal_code": "7244 DK",
    "country_code": "NL",
    "phone_number": "+31612698434",
    "email_address": "jaimy.uil@example.com",
    "organisation": "fab04e42-0901-4e33-839d-4a326d037497"
}

This will result in a customer json object. The id retrieved in this object can be used in the transaction request. It is also possible to create both objects at the same time but please be aware of the added complexity.

This is an example of the response:

{
    "organisation": "fab04e42-0901-4e33-839d-4a326d037497",
    "id": "cbbfa6ec-fb44-4da4-94c4-d81e92fd43e6",
    "title": "ms",
    "initials": "J",
    "first_name": "Jaimy",
    "last_name": "Uil",
    "gender": "female",
    "date_of_birth": "1971-05-12",
    "email_address": "jaimy.uil@example.com",
    "phone_number": "+31612698434",
    "fax_number": "",
    "street_address": "Korte nieuwstraat",
    "house_number": "5846",
    "house_number_suffix": "",
    "postal_code": "7244 DK",
    "city": "Naarden",
    "region": "Zuid-holland",
    "country_code": "NL",
    "social_security_number": "",
    "status": "unverified",
    "status_reason": "",
    "segment": "",
    "created_at": "2016-06-16T11:31:51.881Z",
    "last_status_update": "2016-06-16T11:31:51.881Z"
}

The id field can be used while starting a transaction (field: customer).

Transaction initialization

Once you have received and parsed the form submission from the customer you must initiate the transaction by making a POST request to the following url:

/v1/transaction/start

Here is a valid request body that initiates the Credit card transaction:

{
    "payment_profile": "7c23a50d-8699-431c-a82b-a78718d2b6f6",
    "amount": 14,
    "customer": "cbbfa6ec-fb44-4da4-94c4-d81e92fd43e6",
    "customer_ip": "127.0.0.1",
    "dynamic_descriptor": "orderdesc01",
    "merchant_reference": "my order id",
    "payment_product": "card",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/86.0.4240.198 Safari/537.36",
    "details": {
        "redirect_url": "https://example.com/finalize"
    },
    "webhook_transaction_update": "https://example.com"
}

Remember that the amount must be specified without a decimal point, meaning the value 14 refers to the amount €0.14 EUR.

It is possible to add optional merchant data to a transaction object. For more information click here.

Dynamic descriptor formatting requirements

The dynamic descriptor is a string of up to 100 characters.

Response

In response, we reply with a JSON representation of an initiated transaction. This transaction object also includes the details property, which has been augmented with an approval_url. You will need to redirect the customer to the approval_url so they may authorize the payment.

Here is an example response body of a successful transaction initiation:

{
    "id": "e0377c06-a9e0-43a8-9885-8799a8338b5a",
    "payment_profile": "7c23a50d-8699-431c-a82b-a78718d2b6f6",
    "amount": "14",
    "customer": "cbbfa6ec-fb44-4da4-94c4-d81e92fd43e6",
    "customer_ip": "127.0.0.1",
    "dynamic_descriptor": "orderdesc01",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/86.0.4240.198 Safari/537.36",
    "payment_product": "card",
    "payment_product_type": "card",
    "processor": "card",
    "details": {
        "redirect_url": "https://example.com/finalize",
        "approval_url": "https://api.magnius.com/v1/transaction/e0377c06-a9e0-43a8-9885-8799a8338b5a/authorize"
    },
    "status": "INITIATED",
    "last_status_update": "2016-06-16T11:31:51.881Z",
    "created_at": "2016-06-16T11:31:51.881Z"
}

In case of error while initiating the transaction, the server will respond with a JSON object containing the following fields.

• message {String} — A message describing the error.
• details {Object} [Optional] — An object containing details about the transaction. The format of this object depends on the nature of the error.

Redirect the customer

Once the transaction has been successfully initiated, you should redirect the customer to the approval_url.

At the end of the authorization process, the customer is redirected to the redirect_url you provided when you initiated the transaction. If something goes wrong during this process, we will try, whenever possible, to redirect the customer, such that the customer always ends up on your server.

In the event of an unexpected issue during the redirection process, an additional error query parameter is also appended to the url. This parameter is an encoded string (as defined by the encodeURIComponent presented in ECMAScript ECMA-262) which gives further information about the nature of the error.

Transaction status

The status of the transaction remains unknown until you query its status from our server. Therefore, a query parameter transaction_id is appended to the redirect_url you provided. This refers to the ID we generated for the transaction, which you must use in order to retrieve the status of the transaction.

The transaction status can be checked in two ways:
GET /v1/transaction/{transaction id}/checkoutsuccess
GET /v1/transaction/{transaction id}

The normal transaction GET results in the full transaction while the "checkoutsuccess" addition results in only the necessary information to determine if the transaction was a success. For example:

HTTP Code: 200

{
    "status": "SETTLEMENT_COMPLETED",
    "status_reason": "",
    "success": true
}

Transaction successful?

Generally speaking merchants accept both SETTLEMENT_REQUESTED and SETTLEMENT_COMPLETED as a success. This is also how the above mentioned checkoutsuccess endpoint works.

However we would like to point out that a SETTLEMENT_REQUESTED transaction still does have a very small chance of failing. For example when a customer is flagged by authorities after the capture but before settlement.

Due to the very small chance and the fact that settlement can take 1-3 days (depending on the payment method and agreements), merchants usually see SETTLEMENT_REQUESTED as a successful outcome.

Transaction webhooks

To receive transaction notifications we have two different options. Either you can set a general webhook url via the payment profile object (API documentation, field: webhook_transaction_update). The other option is to add the field webhook_transaction_update to the object used to initiate the transaction. This gives the opportunity to add a transaction specific URL.

Transaction outcome testing

For testing the different transaction outcome statuses it's advised to use the "dummy" payment method. This will allow testing the different outcome flows.

A dummy transaction can be initiated by setting payment_product to dummy:

{
    ...
    "payment_product": "dummy",
    ...
}

Advanced outcome testing

For card transactions, different decline or failure outcomes can be tested using the holder name. To do this, select a holder name in the format: response-[number]. For example, using response-2 will result in a decline with a status_reason of "Refused".

To specifically influence the outcome of a recurring subsequent transaction, use the format: repeat-response-[number].

Overview of options:

Recurring transactions

For more information about recurring transactions, please take a look at our recurring guide.