Are you interested in the partner documentation?
Introduction
This document describes how to communicate with the Online Betaalplatform (OBP) REST API, what responses to expect and more importantly which calls to make for a seamless integration. This page is all about the raw JSON API, which means all GETs will return JSON and all POSTs accept JSON data and return JSON as well.
Authentication
You authenticate to the API by providing one of your API keys in the request. We will provide you with both your Sandbox and Production API keys once your account has been setup. You can manage your API keys through your Merchant login.
Security
All API requests must be made over HTTPS or they will fail. You must authenticate for all requests. The API key is the basic auth username; a password is not required.
Please keep in mind that API keys provide many privileges. Make sure to keep them safe.
Live API Url: | https://api.onlinebetaalplatform.nl/v1 |
API Key: | You can find this key in your account |
Sandbox
The OBP Sandbox is a virtual testing environment that mimics the live OBP production environment. All transactions and orders are tests and no actual payments are made nor will the order be processed.
The Sandbox API key is the basic auth username; a password is not required. You will need the following details to be able to log in to the Sandbox API:
Sandbox API Url: | https://api-sandbox.onlinebetaalplatform.nl/v1 |
Sandbox API Key: | You can find this key in your account |
Responses
We use the default HTTP response codes to indicate failure or success of an API request. We will always return a JSON string, even if an error occurred.
Arguments
code: | integer error code |
message: | text message of error |
HTTP response codes
200 | OK | Success |
400 | Bad Request | Missing parameter(s). |
401 | Unauthorized | Invalid or revoked API key. |
402 | Request Failed | Parameter(s) OK but something went wrong. |
404 | Not Found | Resource doesn't exist. |
50X | Server Errors | Temporary problem on our side. |
Errors
Example response when creating a transaction without providing the required merchant_uid:
{
"error": {
"code": 1935,
"message": "Missing required merchant_uid"
}
}
Pagination
Use the pagination to navigate when having many results.
Arguments
page: | integer the number of the current page |
perpage: | integer the limit of objects to be returned. Limit can range between 1 and 100 items. |
Response list object
object: | string with value "list" |
url: | string, url |
has_more: | boolean |
total_item_count: | number |
items_per_page: | number |
current_page: | number |
last_page: | number |
data: | array |
Example Request
curl https://api.onlinebetaalplatform.nl/v1/transactions \
-u a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p: \
-d page=2 \
-d perpage=10
Example Response
{
"livemode": true,
"object": "list",
"url": "/v1/transactions",
"has_more": true,
"total_item_count": 259,
"items_per_page": 10,
"current_page": 2,
"last_page": 26,
"data": []
}
Expanding Objects
Many objects contain a reference to another object. Those objects can be expanded inline with the expand
parameter. The availability of the expand
parameter and its options differ per request and are noted in the request descriptions.
You can nest expand requests with the dot property. For example, requesting a transaction including the related order and customer details can be done by requesting order
and order.customer
. The order property will be expanded into a full order object and the customer property within the order object will be transformed into a full customer object.
curl https://api.onlinebetaalplatform.nl/v1/transactions/tra_1a2b3cd8e564 \
-u a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p: \
-d expand[]=order \
-d expand[]=order.customer
Arguments
expand: | string name of expandable object |
Example Request
Expand the transaction with the order details.
curl https://api.onlinebetaalplatform.nl/v1/transactions/tra_1a2b3cd8e564 \
-u a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p: \
-d expand[]=order
Example Response
{
"livemode": true,
"uid": "tra_1a2b3cd8e564",
"object": "transaction",
...
"metadata": [],
"statuses":[],
"order": {
uid: "ord_1a2b3c6accb9",
object: "order",
created: 1524083451,
updated: 1524083451,
processed: true,
price: 6000,
shipping: 695,
discount: 0,
street: "Holthuisstraat",
housenumber: "157",
housenumber_addition: null,
zipcode: "1249 HN",
city: "Sinderen",
state: "Gelderland",
country: null,
customer: {}
}
}
Metadata
Use the metadata
parameter to store additional key-value information of an object. A useful example could be to store your corresponding unique identifier of an OBP object.
Example Request
curl https://api.onlinebetaalplatform.nl/v1/transactions \
-u a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p: \
-X POST
-d buyer_name_first=John \
-d buyer_name_last=Tester \
-d buyer_emailaddress="john@tester.dev" \
-d products[0][name]="WakeUp Light" \
-d products[0][ean]=842658921456874 \
-d products[0][price]=10779 \
-d products[0][quantity]=1 \
-d products[0][shipping_costs]=675 \
-d products[0][total_price]=11454 \
-d return_url="https://developer.dev/return/" \
-d notify_url="https://developer.dev/notify/" \
-d metadata[external_id]=2015486
Notifications
We provide a number of notifications which will be sent to the configured webhook or notify_url
.
All notifications will POST the following data to the webhook:
uid: | string notification identifier |
type: | string notification type |
created: | timestamp |
object_uid: | string unique object identifier |
object_type: | string object type, one of transaction or merchant |
object_url: | string, url direct link to object (details) |
Use the notification type to determine the required action you would need to take in your own system. Use the object UID and type to determine the related resource. Follow the object_url to retrieve the resource details.
Notifications
Type | Description |
---|---|
transaction.status.changed | When a transaction status changed |
Example Post
When a transaction status changes, the following notification will be posted to the webhook.
{
"uid":"not_1a2b3c9beb0d",
"type":"transaction.status.changed",
"created":1524083451,
"object_uid":"tra_1a2b3cd8e564",
"object_type":"transaction",
"object_url":"/v1/transactions/tra_1a2b3cd8e564"
}
Transactions
You can retrieve individual transactions as well as a list of transactions.
With our advanced payment flow integration it is possible to create direct- or email transactions. Use checkout
to initiate the responsive OBP checkout.
Transaction object
uid: | string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object: | string with value "transaction" | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
created: | timestamp | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
updated: | timestamp | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
completed: | timestamp | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
mechant_uid: | string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
checkout: | boolean | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
payment_method: | string, one of ideal, paypal, bcmc or sepa | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
payment_flow: | string, one of direct or email | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
payment_details: | array | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
amount: | number, transaction amount in cents | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
return_url: | string, url | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
redirect_url: | string, url | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
notify_url: | string, url | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
status: | string, one of completed, refunded or chargeback. Single-field representation of the last updated status value. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
metadata: | array, see Metadata | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
statuses: | array, see Transaction Statuses | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
order: | array, see Order object | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
escrow: | array, see Escrow object | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Create a transaction
Create a transaction using the following attributes. An initiated transaction has a unique identifier which we provide in the response.
profile_uid: | optional default first profile UID Merchant Profile UID |
||||||||||
checkout: |
optional default is true true use checkout false payment only
|
||||||||||
payment_method: |
optional default is null, all payment methods are availableideal iDEAL selected as payment method paypal PayPal selected as payment method bcmc Bancontact/Mister Cash selected as payment method sepa SEPA selected as payment method
|
||||||||||
payment_flow: |
optional default is directdirect A direct payment with or without a checkout optionemail An email will be send to the emailaddress of the customer with a link to process the payment. |
||||||||||
escrow: |
optional default is false true false
|
||||||||||
escrow_period: | optional Escrow period in days |
||||||||||
escrow_date: | optional Escrow end datetime in YYYY-MM-DD HH:MM:SS format |
||||||||||
locale: |
optional locale used for transactionnl en fr |
||||||||||
buyer_name_first: | optional if payment_flow is email the buyer's first name |
||||||||||
buyer_name_last: | optional if payment_flow is email the buyer's last name |
||||||||||
buyer_emailaddress: | required only if payment_flow is email the buyer's emailaddress |
||||||||||
products: |
required array products to be added to the checkout.
|
||||||||||
shipping_costs: | optional default is account setting number, shipping costs in cents. E.g. 10000 cents for a €100,00 product. |
||||||||||
discount: | optional default is 0 number, discount in cents. E.g. 10000 cents for a €100,00 product. |
||||||||||
total_price: | required number, total price in cents. |
||||||||||
return_url: | required the return url the customer is redirected to once the payment is completed |
||||||||||
notify_url: | optional notification url to receive status updates |
||||||||||
metadata: | optional default is {} a set of key-value pairs that you can attach to the transaction object to store additional data |
Definition
POST https://api.onlinebetaalplatform.nl/v1/transactions
Example Request
cURL example for creating a transaction for a customer buying just 1 product, including some metadata and a URL to receive notifications regarding this transactions.
curl https://api.onlinebetaalplatform.nl/v1/transactions \
-u a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p: \
-d buyer_name_first=John \
-d buyer_name_last=Tester \
-d buyer_emailaddress="john@tester.dev" \
-d products[0][name]="WakeUp Light" \
-d products[0][ean]=842658921456874 \
-d products[0][price]=10779 \
-d products[0][quantity]=1 \
-d shipping_costs=675 \
-d total_price=11454 \
-d return_url="https://developer.dev/return/" \
-d notify_url="https://developer.dev/notify/" \
-d metadata[external_id]=2015486
Response
{
"livemode": true,
"uid": "tra_1a2b3cd8e564",
"object": "transaction",
"created": 1524083451,
"updated": 1524169848,
"completed": null,
"checkout": true,
"payment_method": "ideal",
"payment_flow": "direct",
"payment_details": [],
"amount": "12129",
"return_url": "https://developer.dev/return/",
"redirect_url": "https://onlinebetaalplatform.nl/nl/betalen/?trx=tra_1a2b3cd8e564",
"notify_url": "https://developer.dev/notify/",
"status": "created",
"metadata": [{
"key": "external_id",
"value": "2015486"
}],
"statuses": [{
"uid": "sta_1a2b3c346ae2",
"object": "status",
"created": 1524083451,
"updated": 1524083451,
"status": "created"
}],
"order": {},
"escrow": {}
}
Retrieve a transaction
Retrieve the transaction object based on the transaction UID.
Definition
GET https://api.onlinebetaalplatform.nl/v1/transactions/tra_1a2b3cd8e564
Example Request
curl https://api.onlinebetaalplatform.nl/v1/transactions/tra_1a2b3cd8e564 \
-u a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p:
Example Response
{
"livemode": true,
"uid": "tra_1a2b3cd8e564",
"object": "transaction",
"created": 1524083451,
"updated": 1524169848,
"completed": null,
"checkout": true,
"payment_method": "ideal",
"payment_flow": "direct",
"payment_details": [],
"amount": 10,
"return_url": "https://developer.dev/return/",
"redirect_url": "https://onlinebetaalplatform.nl/nl/merchant/betalen/?trx=tra_1a2b3cd8e564",
"notify_url": "https://developer.dev/notify/",
"status": "created",
"metadata": [{
"key": "external_id",
"value": "2015486"
}],
"statuses": [],
"order": {},
"escrow": {}
}
Retrieve all transactions
Retrieve a list of all transactions in OBP. See Pagination how to navigate having many results.
Definition
GET https://api.onlinebetaalplatform.nl/v1/transactions
Example Request
curl https://api.onlinebetaalplatform.nl/v1/transactions \
-u a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p:
Example response
{
"livemode": true,
"object": "list",
"url": "/v1/transactions",
"has_more": true,
"total_item_count": 259,
"items_per_page": 10,
"current_page": 1,
"last_page": 26,
"data": [
{
"uid": "tra_1a2b3cd8e564",
"object": "transaction",
"created": 1524083451,
"updated": 1524169848,
"completed": null,
"checkout": true,
"payment_method": "ideal",
"payment_flow": "direct",
"payment_details": [],
"amount": 10,
"return_url": "https://developer.dev/return/",
"redirect_url": "https://onlinebetaalplatform.nl/nl/merchant/betalen/?trx=tra_1a2b3cd8e564",
"notify_url": "https://developer.dev/notify/",
"status": "created",
"metadata": [{
"key": "external_id",
"value": "2015486"
}],
"statuses": [],
"order": {},
"escrow": {}
},
{
...
}]
}
Transaction Statuses
The list of all possible transaction statuses:
Created: | Transaction is created and no user action took place. |
Expired: | Transaction is expired either because the buyer did not complete the checkout flow within the allowed time or because the transaction expiration date has passed. |
Pending: | Transaction is awaiting user action or awaiting payment confirmation by selected payment method. |
Completed: | Transaction is completed, payment is confirmed. |
Cancelled: | Transaction is consciously cancelled by the buyer. |
Failed: | Transaction failed due to a payment method error or payment was denied by (creditcard) issuer. |
Refunded: | The transaction is (partially) refunded to the buyer. A single transaction can have multiple refunds. |
Chargeback: | For PayPal transaction only. The funds have been removed from your account balance and returned to the buyer. |
Reserved: | Transaction is completed and "in escrow", payment is confirmed. |
Flow | Final status |
---|---|
Created - Expired | Expired |
Created - Pending - Expired | Expired |
Created - Pending - Cancelled | Cancelled |
Created - Pending - Completed | Completed |
Created - Pending - Reserved - Completed | Completed |
Created - Pending - Completed - Chargeback | Chargeback |
Created - Pending - Completed - Refunded | Refunded |
statuses
in order to view the complete transaction status history.
Example Request
curl https://api.onlinebetaalplatform.nl/v1/transactions/tra_1a2b3cd8e564 \
-u a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p: \
-d expand[]=statuses
Order
When receiving the transaction it is possible to expand the transaction with the order
object.
Order object
uid: | string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
object: | string with value "order" | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
created: | timestamp | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
updated: | timestamp | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
processed: | boolean | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
price: | number, order amount in cents | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
shipping: | number, shipping costs in cents | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
discount: | number, discount in cents | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
street: | string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
housenumber: | number | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
housenumber_addition: | string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
zipcode: | string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
city: | string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
state: | string | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
country: | string with as value the country code of a country (e.g. NLD for Netherlands) | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
customer: | array, see Customer | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|
Customer
Get the Customer object to expand the transaction with order.customer
.
Customer object
uid: | string | ||||
object: | string with value "customer" | ||||
created: | timestamp | ||||
updated: | timestamp | ||||
name |
array
|
||||
name_first: | string | ||||
name_last: | string | ||||
birthdate: | date | ||||
emailaddress: | string | ||||
phonenumber: | string | ||||
company: | string |
Refunds
A refund is only possible if the funds of the transaction have not yet been entirely refunded. Direct PayPal transactions cannot be refunded from within OBP but have to be refunded from the PayPal environment itself.
Refund object
uid: | string |
object: | string with value "refund" |
created: | timestamp |
updated: | timestamp |
paid: | timestamp |
amount: | number, refund amount in cents |
status: | string, one of created or completed |
message: | text |
internal reason: | text |
Refund statuses
created: | the refund is initiated, OBP will pay the amount to the customer |
completed: | the refund amount is paid to the customer |
Create a Refund
Create a refund using the following attributes. An initiated refund has a unique identifier which we give back in the response.
amount: | required refund amount in cents |
message: | optional email message to the original customer |
internal reason: | optional internal reason |
Definition
POST https://api.onlinebetaalplatform.nl/v1/transactions/tra_1a2b3cd8e564/refunds
Example Request
curl https://api.onlinebetaalplatform.nl/v1/transactions/tra_1a2b3cd8e564/refunds \
-u a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p: \
-d amount=6750 \
-d message="As agreed a fully refund" \
-d internal_reason="Customer is not satisfied with product"
Example Response
{
"livemode": true,
"uid": "ref_1a2b3c824f15",
"object": "refund",
"created": 1524083451,
"updated": 1524083451,
"paid": null,
"amount": 6750,
"status": "created",
"message": "As agreed a fully refund",
"internal_reason": "Customer is not satisfied with product"
}
Retrieve a Refund
Perform a request on the transaction object to retrieve all refunds of the transaction.
Definition
GET https://api.onlinebetaalplatform.nl/v1/transactions/tra_1a2b3cd8e564/refunds
Example Request
curl https://api.onlinebetaalplatform.nl/v1/transactions/tra_1a2b3cd8e564/refunds \
-u a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p:
Example Response
{
"livemode":true,
"object": "list",
"url": "/v1/transactions/tra_1a2b3cd8e564/refunds",
"has_more": true,
"total_item_count": 2,
"items_per_page": 10,
"current_page": 1,
"last_page": 1,
"data": [
{
"uid": "ref_1a2b3c824f15",
"object": "refund",
"created": 1524083451,
"updated": 1524083451,
"paid": null,
"amount": 6750,
"status": "created",
"message": "As agreed a fully refund",
"internal_reason": "Customer is not satisfied with product"
},
{
...
}]
}
Escrow
Get the Escrow object to expand the transaction with escrow
.
Escrow object
uid: | string |
object: | string with value "escrow" |
period: | integer |
start: | timestamp |
end: | timestamp |