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_1a2b3c8dbfe8  \
    -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_1a2b3c8dbfe8 \
   -u a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p: \
   -d expand[]=order

Example Response


{
    "livemode": true,
    "uid": "tra_1a2b3c8dbfe8",
    "object": "transaction",
    ...
    "metadata": [],
    "statuses":[],
    "order": {
        uid: "ord_1a2b3cafb9bf",
        object: "order",
        created: 1498120690,
        updated: 1498120690,
        processed: true,
        price: 6000,
        shipping: 695,
        discount: 0,
        street: "van Beeckhof",
        housenumber: "208",
        housenumber_addition: null,
        zipcode: "7764 RC",
        city: "Langerak",
        state: "Noord-Holland",
        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_1a2b3c8da6b0",
    "type":"transaction.status.changed",
    "created":1498120690,
    "object_uid":"tra_1a2b3c8dbfe8",
    "object_type":"transaction",
    "object_url":"/v1/transactions/tra_1a2b3c8dbfe8"
}

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
uid: string
object: string with value "status"
created: timestamp
updated: timestamp
status: string
order: array, see 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)
Code Country
afg afghanistan
alb albania
dza algeria
asm american samoa
and andorra
ago angola
aia anguilla
ata antarctica
atg antigua and barbuda
arg argentina
arm armenia
abw aruba
aus australia
aut austria
aze azerbaijan
bhs bahamas
bhr bahrain
bgd bangladesh
brb barbados
blr belarus
bel belgium
blz belize
ben benin
bmu bermuda
btn bhutan
bol bolivia
bih bosnia and herzegovina
bwa botswana
bvt bouvet island
bra brazil
iot british indian ocean territory
brn brunei darussalam
bgr bulgaria
bfa burkina faso
bdi burundi
khm cambodia
cmr cameroon
can canada
cpv cape verde
cym cayman islands
caf central african republic
tcd chad
chl chile
chn china
cxr christmas island
cck cocos (keeling) islands
col colombia
com comoros
cog congo
cok cook islands
cri costa rica
civ cote d'ivoire
hrv croatia (local name: hrvatska)
cub cuba
cyp cyprus
cze czech republic
dnk denmark
dji djibouti
dma dominica
dom dominican republic
tls east timor
ecu ecuador
egy egypt
slv el salvador
gnq equatorial guinea
eri eritrea
est estonia
eth ethiopia
flk falkland islands (malvinas)
fro faroe islands
fji fiji
fin finland
fra france
fxx france, metropolitan
guf french guiana
pyf french polynesia
atf french southern territories
gab gabon
gmb gambia
geo georgia
deu germany
gha ghana
gib gibraltar
grc greece
grl greenland
grd grenada
glp guadeloupe
gum guam
gtm guatemala
gin guinea
gnb guinea-bissau
guy guyana
hti haiti
hmd heard island & mcdonald islands
hnd honduras
hkg hong kong
hun hungary
isl iceland
ind india
idn indonesia
irn iran, islamic republic of
irq iraq
irl ireland
isr israel
ita italy
jam jamaica
jpn japan
jor jordan
kaz kazakhstan
ken kenya
kir kiribati
prk korea, democratic people's republic of
kor korea, republic of
kwt kuwait
kgz kyrgyzstan
lao lao people's democratic republic
lva latvia
lbn lebanon
lso lesotho
lbr liberia
lby libyan arab jamahiriya
lie liechtenstein
ltu lithuania
lux luxembourg
mac macau
mkd macedonia, the former yugoslav republic of
mdg madagascar
mwi malawi
mys malaysia
mdv maldives
mli mali
mlt malta
mhl marshall islands
mtq martinique
mrt mauritania
mus mauritius
myt mayotte
mex mexico
fsm micronesia, federated states of
mda moldova, republic of
mco monaco
mng mongolia
msr montserrat
mar morocco
moz mozambique
mmr myanmar
nam namibia
nru nauru
npl nepal
nld netherlands
ant netherlands antilles
ncl new caledonia
nzl new zealand
nic nicaragua
ner niger
nga nigeria
niu niue
nfk norfolk island
mnp northern mariana islands
nor norway
omn oman
pak pakistan
plw palau
pan panama
png papua new guinea
pry paraguay
per peru
phl philippines
pcn pitcairn
pol poland
prt portugal
pri puerto rico
qat qatar
reu reunion
rou romania
rus russian federation
rwa rwanda
kna saint kitts and nevis
lca saint lucia
vct saint vincent and the grenadines
wsm samoa
smr san marino
stp sao tome and principe
sau saudi arabia
sen senegal
srb serbia
syc seychelles
sle sierra leone
sgp singapore
svk slovakia (slovak republic)
svn slovenia
slb solomon islands
som somalia
zaf south africa
esp spain
lka sri lanka
shn saint helena
spm saint pierre and miquelon
sdn sudan
sur suriname
sjm svalbard and jan mayen islands
swz swaziland
swe sweden
che switzerland
syr syrian arab republic
twn taiwan, province of china
tjk tajikistan
tza tanzania, united republic of
tha thailand
tgo togo
tkl tokelau
ton tonga
tto trinidad and tobago
tun tunisia
tur turkey
tkm turkmenistan
tca turks and caicos islands
tuv tuvalu
uga uganda
ukr ukraine
are united arab emirates
gbr united kingdom
usa united states
umi united states minor outlying islands
ury uruguay
uzb uzbekistan
vut vanuatu
vat vatican city state (holy see)
ven venezuela
vnm vietnam
vgb virgin islands (british)
vir virgin islands (u.s.)
wlf wallis and futuna islands
esh western sahara
yem yemen
yug yugoslavia
zar zaire
zmb zambia
zwe zimbabwe
customer: array, see Customer
uid: string
object: string with value "customer"
created: timestamp
updated: timestamp
name array
first: string
last: string
name_first: string
name_last: string
birthdate: date
emailaddress: string
phonenumber: string
company: string
escrow: array, see Escrow object
uid: string
object: string with value "escrow"
period: integer
start: timestamp
end: timestamp

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 available
ideal 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 direct
direct A direct payment with or without a checkout option
email 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 transaction
nl
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.
name: required
product name
ean: optional
product EAN (European Article Numbering) code
code: optional
product code
price: required
number, product price in cents. E.g. 10000 cents for a €100,00 product.
quantity: required
number, number of products
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_1a2b3c8dbfe8",
    "object": "transaction",
    "created": 1498120690,
    "updated": 1498207087,
    "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_1a2b3c8dbfe8",
    "notify_url": "https://developer.dev/notify/",
    "status": "created",
    "metadata": [{
        "key": "external_id",
        "value": "2015486"
    }],
    "statuses": [{
        "uid": "sta_1a2b3c3129e2",
        "object": "status",
        "created": 1498120690,
        "updated": 1498120690,
        "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_1a2b3c8dbfe8

Example Request


curl https://api.onlinebetaalplatform.nl/v1/transactions/tra_1a2b3c8dbfe8 \ 
    -u a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p:

Example Response


{
    "livemode": true,
    "uid": "tra_1a2b3c8dbfe8",
    "object": "transaction",
    "created": 1498120690,
    "updated": 1498207087,
    "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_1a2b3c8dbfe8",
    "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_1a2b3c8dbfe8",
        "object": "transaction",
        "created": 1498120690,
        "updated": 1498207087,
        "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_1a2b3c8dbfe8",
        "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
Expand the transaction with statuses in order to view the complete transaction status history.

Example Request


curl https://api.onlinebetaalplatform.nl/v1/transactions/tra_1a2b3c8dbfe8 \
   -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)
Code Country
afg afghanistan
alb albania
dza algeria
asm american samoa
and andorra
ago angola
aia anguilla
ata antarctica
atg antigua and barbuda
arg argentina
arm armenia
abw aruba
aus australia
aut austria
aze azerbaijan
bhs bahamas
bhr bahrain
bgd bangladesh
brb barbados
blr belarus
bel belgium
blz belize
ben benin
bmu bermuda
btn bhutan
bol bolivia
bih bosnia and herzegovina
bwa botswana
bvt bouvet island
bra brazil
iot british indian ocean territory
brn brunei darussalam
bgr bulgaria
bfa burkina faso
bdi burundi
khm cambodia
cmr cameroon
can canada
cpv cape verde
cym cayman islands
caf central african republic
tcd chad
chl chile
chn china
cxr christmas island
cck cocos (keeling) islands
col colombia
com comoros
cog congo
cok cook islands
cri costa rica
civ cote d'ivoire
hrv croatia (local name: hrvatska)
cub cuba
cyp cyprus
cze czech republic
dnk denmark
dji djibouti
dma dominica
dom dominican republic
tls east timor
ecu ecuador
egy egypt
slv el salvador
gnq equatorial guinea
eri eritrea
est estonia
eth ethiopia
flk falkland islands (malvinas)
fro faroe islands
fji fiji
fin finland
fra france
fxx france, metropolitan
guf french guiana
pyf french polynesia
atf french southern territories
gab gabon
gmb gambia
geo georgia
deu germany
gha ghana
gib gibraltar
grc greece
grl greenland
grd grenada
glp guadeloupe
gum guam
gtm guatemala
gin guinea
gnb guinea-bissau
guy guyana
hti haiti
hmd heard island & mcdonald islands
hnd honduras
hkg hong kong
hun hungary
isl iceland
ind india
idn indonesia
irn iran, islamic republic of
irq iraq
irl ireland
isr israel
ita italy
jam jamaica
jpn japan
jor jordan
kaz kazakhstan
ken kenya
kir kiribati
prk korea, democratic people's republic of
kor korea, republic of
kwt kuwait
kgz kyrgyzstan
lao lao people's democratic republic
lva latvia
lbn lebanon
lso lesotho
lbr liberia
lby libyan arab jamahiriya
lie liechtenstein
ltu lithuania
lux luxembourg
mac macau
mkd macedonia, the former yugoslav republic of
mdg madagascar
mwi malawi
mys malaysia
mdv maldives
mli mali
mlt malta
mhl marshall islands
mtq martinique
mrt mauritania
mus mauritius
myt mayotte
mex mexico
fsm micronesia, federated states of
mda moldova, republic of
mco monaco
mng mongolia
msr montserrat
mar morocco
moz mozambique
mmr myanmar
nam namibia
nru nauru
npl nepal
nld netherlands
ant netherlands antilles
ncl new caledonia
nzl new zealand
nic nicaragua
ner niger
nga nigeria
niu niue
nfk norfolk island
mnp northern mariana islands
nor norway
omn oman
pak pakistan
plw palau
pan panama
png papua new guinea
pry paraguay
per peru
phl philippines
pcn pitcairn
pol poland
prt portugal
pri puerto rico
qat qatar
reu reunion
rou romania
rus russian federation
rwa rwanda
kna saint kitts and nevis
lca saint lucia
vct saint vincent and the grenadines
wsm samoa
smr san marino
stp sao tome and principe
sau saudi arabia
sen senegal
srb serbia
syc seychelles
sle sierra leone
sgp singapore
svk slovakia (slovak republic)
svn slovenia
slb solomon islands
som somalia
zaf south africa
esp spain
lka sri lanka
shn saint helena
spm saint pierre and miquelon
sdn sudan
sur suriname
sjm svalbard and jan mayen islands
swz swaziland
swe sweden
che switzerland
syr syrian arab republic
twn taiwan, province of china
tjk tajikistan
tza tanzania, united republic of
tha thailand
tgo togo
tkl tokelau
ton tonga
tto trinidad and tobago
tun tunisia
tur turkey
tkm turkmenistan
tca turks and caicos islands
tuv tuvalu
uga uganda
ukr ukraine
are united arab emirates
gbr united kingdom
usa united states
umi united states minor outlying islands
ury uruguay
uzb uzbekistan
vut vanuatu
vat vatican city state (holy see)
ven venezuela
vnm vietnam
vgb virgin islands (british)
vir virgin islands (u.s.)
wlf wallis and futuna islands
esh western sahara
yem yemen
yug yugoslavia
zar zaire
zmb zambia
zwe zimbabwe
customer: array, see Customer
uid: string
object: string with value "customer"
created: timestamp
updated: timestamp
name array
first: string
last: string
name_first: string
name_last: string
birthdate: date
emailaddress: string
phonenumber: string
company: string

Update an Order

Update an order using one of the following parameters. Parameters that are not provided will be left unchanged.

processed: optional
true if order is processed or false if order is unprocessed
street: optional
street name
housenumber: optional
housenumber
housenumber_addition: optional
housenumber addition (e.g. "a" for housenumber "10a")
zipcode: optional
zipcode
city: optional
city
state: optional
state
country: optional
the country code of a country (e.g. NLD for Netherlands)
Code Country
afg afghanistan
alb albania
dza algeria
asm american samoa
and andorra
ago angola
aia anguilla
ata antarctica
atg antigua and barbuda
arg argentina
arm armenia
abw aruba
aus australia
aut austria
aze azerbaijan
bhs bahamas
bhr bahrain
bgd bangladesh
brb barbados
blr belarus
bel belgium
blz belize
ben benin
bmu bermuda
btn bhutan
bol bolivia
bih bosnia and herzegovina
bwa botswana
bvt bouvet island
bra brazil
iot british indian ocean territory
brn brunei darussalam
bgr bulgaria
bfa burkina faso
bdi burundi
khm cambodia
cmr cameroon
can canada
cpv cape verde
cym cayman islands
caf central african republic
tcd chad
chl chile
chn china
cxr christmas island
cck cocos (keeling) islands
col colombia
com comoros
cog congo
cok cook islands
cri costa rica
civ cote d'ivoire
hrv croatia (local name: hrvatska)
cub cuba
cyp cyprus
cze czech republic
dnk denmark
dji djibouti
dma dominica
dom dominican republic
tls east timor
ecu ecuador
egy egypt
slv el salvador
gnq equatorial guinea
eri eritrea
est estonia
eth ethiopia
flk falkland islands (malvinas)
fro faroe islands
fji fiji
fin finland
fra france
fxx france, metropolitan
guf french guiana
pyf french polynesia
atf french southern territories
gab gabon
gmb gambia
geo georgia
deu germany
gha ghana
gib gibraltar
grc greece
grl greenland
grd grenada
glp guadeloupe
gum guam
gtm guatemala
gin guinea
gnb guinea-bissau
guy guyana
hti haiti
hmd heard island & mcdonald islands
hnd honduras
hkg hong kong
hun hungary
isl iceland
ind india
idn indonesia
irn iran, islamic republic of
irq iraq
irl ireland
isr israel
ita italy
jam jamaica
jpn japan
jor jordan
kaz kazakhstan
ken kenya
kir kiribati
prk korea, democratic people's republic of
kor korea, republic of
kwt kuwait
kgz kyrgyzstan
lao lao people's democratic republic
lva latvia
lbn lebanon
lso lesotho
lbr liberia
lby libyan arab jamahiriya
lie liechtenstein
ltu lithuania
lux luxembourg
mac macau
mkd macedonia, the former yugoslav republic of
mdg madagascar
mwi malawi
mys malaysia
mdv maldives
mli mali
mlt malta
mhl marshall islands
mtq martinique
mrt mauritania
mus mauritius
myt mayotte
mex mexico
fsm micronesia, federated states of
mda moldova, republic of
mco monaco
mng mongolia
msr montserrat
mar morocco
moz mozambique
mmr myanmar
nam namibia
nru nauru
npl nepal
nld netherlands
ant netherlands antilles
ncl new caledonia
nzl new zealand
nic nicaragua
ner niger
nga nigeria
niu niue
nfk norfolk island
mnp northern mariana islands
nor norway
omn oman
pak pakistan
plw palau
pan panama
png papua new guinea
pry paraguay
per peru
phl philippines
pcn pitcairn
pol poland
prt portugal
pri puerto rico
qat qatar
reu reunion
rou romania
rus russian federation
rwa rwanda
kna saint kitts and nevis
lca saint lucia
vct saint vincent and the grenadines
wsm samoa
smr san marino
stp sao tome and principe
sau saudi arabia
sen senegal
srb serbia
syc seychelles
sle sierra leone
sgp singapore
svk slovakia (slovak republic)
svn slovenia
slb solomon islands
som somalia
zaf south africa
esp spain
lka sri lanka
shn saint helena
spm saint pierre and miquelon
sdn sudan
sur suriname
sjm svalbard and jan mayen islands
swz swaziland
swe sweden
che switzerland
syr syrian arab republic
twn taiwan, province of china
tjk tajikistan
tza tanzania, united republic of
tha thailand
tgo togo
tkl tokelau
ton tonga
tto trinidad and tobago
tun tunisia
tur turkey
tkm turkmenistan
tca turks and caicos islands
tuv tuvalu
uga uganda
ukr ukraine
are united arab emirates
gbr united kingdom
usa united states
umi united states minor outlying islands
ury uruguay
uzb uzbekistan
vut vanuatu
vat vatican city state (holy see)
ven venezuela
vnm vietnam
vgb virgin islands (british)
vir virgin islands (u.s.)
wlf wallis and futuna islands
esh western sahara
yem yemen
yug yugoslavia
zar zaire
zmb zambia
zwe zimbabwe
customer: optional
customer details
name optional array
first: optional
first name
last: optional
last name
birthdate optional
date of birth
emailaddress optional
emailaddress
phonenumber optional
phonenumber
company optional
name of company

Definition


POST https://api.onlinebetaalplatform.nl/v1/orders/ord_1a2b3cafb9bf

Example Request


curl https://api.onlinebetaalplatform.nl/v1/orders/ord_1a2b3cafb9bf \
    -u a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p: \
    -d processed=true \
    -d customer['name']['first']="John"

Example Response


{
    "livemode":true,
    "uid":"ord_1a2b3cafb9bf",
    "object": "order",
    "created": 1498120690,
    "updated": 1498207087,
    "processed":true,
    "price":11454,
    "shipping":675,
    "discount":0,
    "street":van Beeckhof,
    "housenumber":208,
    "housenumber_addition":null,
    "zipcode":"7764 RC",
    "city":"Langerak",
    "state":"Noord-Holland",
    "country":"NLD",
    "customer": {
    	"name": {
    	    "first":"John",
    	    "last":"Tester"
        },
        "birthdate": null,
        "emailaddress":"john@tester.dev",
        "phonenumber":"(037) 9000797",
        "company":"Roessink"
    }
}

Retrieve an Order

This request retrieves the details of an order.

Definition


GET https://api.onlinebetaalplatform.nl/v1/orders/ord_1a2b3cafb9bf

Example Request


curl https://api.onlinebetaalplatform.nl/v1/orders/ord_1a2b3cafb9bf \
    -u a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p:

Example Response


{
    "livemode": true,
    "uid": "ord_1a2b3cafb9bf",
    "object": "order",
    "created": 1498120690,
    "updated": 1498207087,
    "processed": true,
    "price": 11454,
    "shipping": 675,
    "discount": 0,
    "street": "van Beeckhof",
    "housenumber": "208",
    "housenumber_addition": null,
    "zipcode": "7764 RC",
    "city": "Langerak",
    "state": "Noord-Holland",
    "country": "NLD",
    "customer": {
    	"name": {
    	    "first": "John",
    	    "last": "Tester"
        },
        "birthdate": null,
        "emailaddress": "john@tester.dev",
        "phonenumber": (037) 9000797,
        "company": "Roessink"
    }
}

Retrieve all Orders

Retrieve a list of all orders in OBP. See Pagination how to navigate having many results.

Definition


GET https://api.onlinebetaalplatform.nl/v1/orders

Example Request


curl https://api.onlinebetaalplatform.nl/v1/orders \
    -u a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p:

Example Response



{
    "livemode": true,
    "object": "list",
    "url": "/v1/orders",
    "has_more": true,
    "total_item_count": 259,
    "items_per_page": 10,
    "current_page": 1,
    "last_page": 26,
    "data": [
    {
        "uid": "ord_1a2b3cafb9bf",
        "object": "order",
        "created": 1498120690,
        "updated": 1498207087,
        "processed": true,
        "price": 11454,
        "shipping": 675,
        "discount": 0,
        "street": "van Beeckhof",
        "housenumber": "208",
        "housenumber_addition": null,
        "zipcode": "7764 RC",
        "city": "Langerak",
        "state": "Noord-Holland",
        "country": "NLD",
        "customer": {
        	"name": {
        	    "first": "John",
        	    "last": "Tester"
            },
            "birthdate": null,
            "emailaddress": "john@tester.dev",
            "phonenumber": (037) 9000797,
            "company": "Roessink"
        },
        }
            ...
        {
    }]
}

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
first: string
last: string
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_1a2b3c8dbfe8/refunds

Example Request


curl https://api.onlinebetaalplatform.nl/v1/transactions/tra_1a2b3c8dbfe8/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_1a2b3c835773",
    "object": "refund",
    "created": 1498120690,
    "updated": 1498120690,
    "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_1a2b3c8dbfe8/refunds

Example Request


curl https://api.onlinebetaalplatform.nl/v1/transactions/tra_1a2b3c8dbfe8/refunds \
   -u a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p:

Example Response


{
    "livemode":true,
    "object": "list",
    "url": "/v1/transactions/tra_1a2b3c8dbfe8/refunds",
    "has_more": true,
    "total_item_count": 2,
    "items_per_page": 10,
    "current_page": 1,
    "last_page": 1,
    "data": [
    {
        "uid": "ref_1a2b3c835773",
        "object": "refund",
        "created": 1498120690,
        "updated": 1498120690,
        "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

Discount codes

Use discount codes to provide customers with a discount on a transaction. Discount codes can be used in checkout-flow. Keep in mind use discount batches to make multiple discount codes in just one request.

Discount code object

uid: string
object: string with value "discount_code"
created: timestamp
updated: timestamp
valid_from: timestamp
valid_until: timestamp
code: string
code_type: string, one of once, limit, unique or all
code_limit: number
amount: number
discount_type: string, one of amount or percentage
amount_minimum: number

Create discount code

valid_from required
timestamp
valid_untill: optional default null
timestamp
code: required max. length 25 [a-zA-Z0-9]
name of the code
discount_type: required
amount discount is a fixed amount
percentage discount is a percentage of the total amount
amount: required
amount in cents if discount_type is amount or number between 1 and 100 if discount_type is percentage
code_type: required
once discount code can be used once
unique discount code can be used once by any unique customer
all discount code can be reused and can be used by all customers
code_limit: optional default null
number of how many times this discount code can be used
minimal_amount: optional default null
minimal amount in cents

Definition


POST https://api.onlinebetaalplatform.nl/v1/discountcodes

Example Request


curl https://api.onlinebetaalplatform.nl/v1/discountcodes \
    -u a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p: \
    -d date_started=1495701497 \
    -d code="803712" \
    -d discount_type="amount" \
    -d amount=675 \
    -d code_type="all"

Example Response


{
    "livemode": true,
    "uid": "dis_1a2b3c1a46c1",
    "object": "discount_code",
    "created": 1498120690,
    "updated": 1498207087,
    "valid_from": 1495701497,
    "valid_untill": 1500885497,
    "code": "803712",
    "code_type": "all",
    "code_limit": null,
    "amount": 675,
    "discount_type": "amount",
    "amount_minimum": null
}

Delete a discount code

This request allows for the deletion of a single discount code.

Definition


DELETE https://api.onlinebetaalplatform.nl/v1/discountcodes/dis_1a2b3c1a46c1

Example Request


curl https://api.onlinebetaalplatform.nl/v1/discountcodes/dis_1a2b3c1a46c1 \
    -u a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p: \
    -X DELETE

Example Response


{
    "livemode": true,
    "uid": "dis_1a2b3c1a46c1",
    "deleted": true
}

Retrieve discount code

Retrieve the discount object based on the discount UID.

Definition


GET https://api.onlinebetaalplatform.nl/v1/discountcodes/dis_1a2b3c1a46c1

Example Request


curl https://api.onlinebetaalplatform.nl/v1/discountcodes/dis_1a2b3c1a46c1 \
    -u a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p:

Example Response


{
    "livemode": true,
    "uid": "dis_1a2b3c1a46c1",
    "object": "discount_code",
    "created": 1498120690,
    "updated": 1498207087,
    "valid_from": 1495701497,
    "valid_untill": 1500885497,
    "code": "803712",
    "code_type": "all",
    "code_limit": null,
    "amount": 675,
    "discount_type": "amount",
    "amount_minimum": null
}

Retrieve all single discount codes

Returns a list of all discount codes.

Definition


GET https://api.onlinebetaalplatform.nl/v1/discountcodes

Example Request


curl https://api.onlinebetaalplatform.nl/v1/discountcodes \
    -u a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p:

Example Response


{
    "livemode":true,
    "object": "list",
    "url": "/v1/discountcodes",
    "has_more": true,
    "total_item_count": 12,
    "items_per_page": 10,
    "current_page": 1,
    "last_page": 2,
    "data": [
    {
        "uid": "dis_1a2b3c1a46c1",
        "object": "discount_code",
        "created": 1498120690,
        "updated": 1498207087,
        "valid_from": 1495701497,
        "valid_untill": 1500885497,
        "code": "803712",
        "code_type": "all",
        "code_limit": null,
        "amount": 675,
        "discount_type": "amount",
        "amount_minimum": null,
    },
    {
        ...
    }]
}

Discountbatches

Use discount codes to provide customers with a discount on a transaction. Discount codes can be used in checkout-flow. Create a batch to create multiple discount codes in just one request.

Discount batch object

uid string
object string with value "discount_batch"
created timestamp
updated timestamp
valid_from timestamp
valid_untill timestamp
quantity number
discount_type string, one of amount or percentage
amount number
minimal_amount number
code_type string, one of once, unique or all
code_limit: number
code_prefix string
download_type string, with value "csv"
download_url string, url
notify_url string, url

Create a discount batch

Create a batch to make multiple discount codes in a single request. OBP will create unique codes and send a notification to the notify_url when it is done. Afterwards, it is possible to download the codes from the download_url, which you received in our response.

valid_from: required
timestamp
valid_untill: optional default null
timestamp
quantity: required min. 1 max. 100.000
number of codes
discount_type: required
amount discount is a fixed amount
percentage discount is a percentage of the total amount
amount: required
amount in cents if discount_type is amount or number between 1 and 100 if discount_type is percentage.
minimal_amount: optional default null
minimal amount in cents
code_type: required
once discount code can be used once
unique discount code can be used once by any unique customer
all discount code can be reused by all customers
code_limit: optional default null
number of how many times the generated discount code can be used
code_prefix: optional max. length 8 [a-zA-Z0-9]
all generated codes will begin with this prefix
notify_url: optional url
notification url to receive notification when csv is available

Definition


POST https://api.onlinebetaalplatform.nl/v1/discountbatches

Example Request


curl https://api.onlinebetaalplatform.nl/v1/discountbatches \
    -u a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p: \
    -d valid_from=1495701497 \
    -d quantity=500 \
    -d discount_type="amount" \
    -d amount=675 \
    -d code_type="all" \
    -d code_prefix="OBP" \
    -d notify_url="https://developer.dev/notify/"

Example Reponse


{
    "livemode": true,
    "uid": "dcb_1a2b3c3e260d",
    "object": "discount_batch",
    "created": 1498120690,
    "updated": 1498207087,
    "valid_from": 1495701497,
    "valid_untill": 1500885497,
    "quantity": 500,
    "discount_type": "amount",
    "amount": 675,
    "minimal_amount": null,
    "code_type": "all",
    "code_limit": null,
    "code_prefix": "OBP",
    "download_type": "csv",
    "download_url": "https://download.developer.dev/download/dcb_1a2b3c3e260d",
    "notify_url": "https://developer.dev/notify/"
}

Delete a discount batch

This object allows for the deletion of a discount batch. All generated discount codes connected to this batch will be deleted.

Definition


DELETE https://api.onlinebetaalplatform.nl/v1/discountbatches/dcb_1a2b3c3e260d

Example Request


curl https://api.onlinebetaalplatform.nl/v1/discountbatches/dcb_1a2b3c3e260d \
    -u a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p:
    -X DELETE

Example Response


{
    "livemode": true,
    "uid": "dcb_1a2b3c3e260d",
    "deleted": true
}

Retrieve batch

Retrieve the batch object based on the batch uid.

Definition


GET https://api.onlinebetaalplatform.nl/v1/discountbatches/dcb_1a2b3c3e260d

Example Request


curl https://api.onlinebetaalplatform.nl/v1/discountbatches/dcb_1a2b3c3e260d \
    -u a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p:

Example Response


{
    "livemode": true,
    "uid": "dcb_1a2b3c3e260d",
    "object": "discount_batch",
    "created": 1498120690,
    "updated": 1498207087,
    "valid_from": 1495701497,
    "valid_untill": 1500885497,
    "quantity": 500,
    "discount_type": "amount",
    "amount": 675,
    "code_type": "all",
    "code_limit": null,
    "code_prefix": "OBP",
    "download_type": "csv",
    "download_url": "https://download.developer.dev/download/dcb_1a2b3c3e260d",
    "notify_url": "https://developer.dev/notify/"
}

Retrieve all batches

Retrieve a list of all discount batches in OBP. See Pagination how to navigate having many results.

Definition


GET https://api.onlinebetaalplatform.nl/v1/discountbatches

Example Request


curl https://api.onlinebetaalplatform.nl/v1/discountbatches \
    -u a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p:

Example Response


{
    "livemode": true,
    "object": "list",
    "url": "/v1/discountbatches",
    "has_more": true,
    "total_item_count": 2,
    "items_per_page": 10,
    "current_page": 1,
    "last_page": 1,
    "data": [
    {
       "uid": "dcb_1a2b3c3e260d",
       "object": "discount_batch",
       "created": 1498120690,
       "updated": 1498207087,
       "valid_from": 1495701497,
       "valid_untill": 1500885497,
       "quantity": 500,
       "discount_type": "amount",
       "amount": 675,
       "code_type": "all",
       "code_limit": null,
       "code_prefix": "OBP",
       "download_type": "csv",
       "download_url": "https://download.developer.dev/download/dcb_1a2b3c3e260d",
       "notify_url": "https://developer.dev/notify/"
    },
    {
        ...
    }]
}