Rabobank Docs

Initiate a transaction

POST
/v1/orders/{order_id}/transactions/{transaction_id}/initiate/

Starts a card transaction with a card from the vault. The response is the order, with the transaction updated. This replaces Authenticate a transaction.

  • 3-D Secure by Rabobank: send the vault_token, and optionally the cvc. Redirect your customer to the payment_url of the transaction in the response, so they can authenticate with their bank. Afterwards, they return to your return_url. When 3-D Secure isn't needed, the transaction is processed right away and the payment_url leads to the result page.
  • External 3-D Secure: also send the result of your own 3-D Secure provider in cavv, 3ds_version, 3ds_method_used and ds_transaction_id. The transaction is processed right away. See External 3-D Secure.
  • Recurring charges: send only the vault_token to charge a stored card without your customer, for example to continue a recurring series from another platform.
  • Payouts: send only the vault_token to execute a payout.

Authorization

apiKey
headerAuthorizationBasic <token>

Use your project's API key as the username and leave the password empty. Only use the API key from your server: it gives full access to your project.

Path Parameters

order_id*string

The id of the order.

Formatuuid
transaction_id*string

The id of the transaction, from the transactions of the order.

Formatuuid

Request Body

application/json
  1. body
vault_token*string

The vault_token from the vault.

Formatuuid
cvc?string

The card's CVC or CVV, if you collected it.

Response Body

The transaction has been started. The response contains the order. When your customer has to authenticate, the transaction has status new and its payment_url is where to redirect them. Otherwise the transaction has been processed, check its status.

application/json
  1. response
id*string

Order ID.

Formatuuid
project_id*string

ID of the project the order belongs to.

Formatuuid
merchant_id*string

ID of your merchant account.

Formatuuid
merchant_order_id?string

Your own order reference, shown in the merchant portal. Recommended.

description?string

Description of the order. Recommended.

currency*Currency

ISO 4217 currency code, such as EUR, GBP or USD. Get supported currencies lists the currencies of your project.

Match^[A-Z]{3}$
amount*Amount

Amount in the smallest currency unit, including VAT. 1234 is € 12.34. For currencies without minor units, send the whole amount.

Range0 <= value
status*string

Status of the order. completed, cancelled, expired and error are final. See Order statuses.

Value in"new""processing""completed""cancelled""expired""error"
flags?array<string>

Labels of the order, such as is-test for orders in a test project and is-refund for refund orders.

created*Timestamp

Date and time in ISO 8601 format.

Formatdate-time
modified*Timestamp

Date and time in ISO 8601 format.

Formatdate-time
completed?Timestamp

Date and time in ISO 8601 format.

Formatdate-time
last_transaction_added?string

When the latest transaction was added to the order.

Formatdate-time
expiration_period?Duration

How long the order stays valid, such as PT1H for one hour.

capture_mode?string

Makes every transaction of the order a pre-authorization. Without it, the amount is captured right away. A capture_mode on a transaction overrides it.

  • manual: the amount is reserved until you capture or void it.
  • delayed: the amount is captured automatically when the expiration_period ends.
Value in"manual""delayed"
payment_methods?array<|>

The payment methods to show on the hosted payment page. Without it, every payment method that's active in your project is shown.

transactions?array<>

The payment attempts of the order. When you create the order, send one transaction to pick the payment method yourself. Without it, your customer picks a payment method on the hosted payment page.

order_url?string

The hosted payment page of the order. Redirect your customer here when you didn't send a transaction.

Formaturi
return_url?string

Where your customer goes after the payment, or after 3-D Secure authentication in your own checkout. Without it, your customer stays on the Rabobank result page. Recommended.

Formaturi
failure_url?string

Where your customer goes when the payment fails, with status cancelled, expired or error. Without it, your customer goes to the return_url.

Formaturi
webhook_url?string

Where webhooks for this order are sent. Overrides the webhook URL of your project.

Formaturi
customer?

Your customer. Card schemes use these details for 3-D Secure risk assessment, so complete details lead to more frictionless payments. Your acquirer can require some of them.

order_lines?array<>

The items of the order. Optional for card payments.

client?

The software that sends the request, such as your e-commerce platform or plugin.

extra?

Your own data to store with the order. It's returned when you retrieve the order.

merchant_tags?

Key-value tags copied from your merchant account when the order was created.

events?array<>

Log of what happened to the order. See Transaction events for the events of each transaction.

refunded_amount?integer

The amount refunded on this order so far, in the smallest currency unit.

refund_of_order_id?string

For a refund order, the ID of the original order.

Formatuuid
refund_orders?array<>

IDs of the refund orders of this order.

capture_of_order_id?string

For a capture order, the ID of the original order.

Formatuuid
void_of_order_id?string

For a void order, the ID of the original order.

Formatuuid
chargeback_of_order_id?string

For a chargeback order, the ID of the original order.

Formatuuid
chargeback_orders?array<>

IDs of the chargeback orders of this order.

reversal_of_order_id?string

For a reversal order, the ID of the original order.

Formatuuid
reversal_orders?array<>

IDs of the reversal orders of this order.

related_payment_link_id?string

ID of the payment link the order was created from.

Formatuuid
curl -X POST 'https://api.prod.smartpay.gingerpayments.com/v1/orders/8078d78f-8700-4cfe-94b1-4a777d3400f2/transactions/a5dac3de-d304-4570-922b-373d478b8b3a/initiate/' \  --user "$API_KEY:" \  -H 'Content-Type: application/json' \  -d '{  "vault_token": "d972dc43-6a3d-4dcf-b54e-6e9a0fe325e3",  "cvc": "123"}'
{  "id": "0a73c8e3-7a2f-40ee-8f6c-fa41a37c140a",  "amount": 4000,  "currency": "EUR",  "merchant_order_id": "MIGRATED-SUB-001",  "status": "processing",  "transactions": [    {      "id": "7e5d1b90-2c4a-4f83-b6d1-9a0e3c5f8b27",      "amount": 4000,      "currency": "EUR",      "payment_method": "credit-card",      "payment_method_brand": "visa",      "payment_method_details": {        "approval_code": "08C405",        "authorization_iso_response_code": "00",        "first_network_transaction_id": "MDSIZQ7RH0128",        "network_transaction_id": "MDSIRCRRH0128",        "recurring_type": "recurring",        "schedule_type": "unscheduled",        "vault_token": "ab39817c-7e19-497a-ac7b-23526473b3c1"      },      "status": "accepted"    }  ]}