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

Example Response


{
    "livemode": true,
    "uid": "tra_1a2b3cae06d7",
    "object": "transaction",
    ...
    "metadata": [],
    "statuses":[],
    "order": {
        uid: "ord_1a2b3c63e8b9",
        object: "order",
        created: 1571036751,
        updated: 1571036751,
        processed: true,
        price: 6000,
        shipping: 695,
        discount: 0,
        street: "Hazenveldsteeg",
        housenumber: "241",
        housenumber_addition: null,
        zipcode: "2215 RT",
        city: "Eemshaven",
        state: "Noord-Brabant",
        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_1a2b3c7a34e4",
    "type":"transaction.status.changed",
    "created":1571036751,
    "object_uid":"tra_1a2b3cae06d7",
    "object_type":"transaction",
    "object_url":"/v1/transactions/tra_1a2b3cae06d7"
}

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
cod Congo
nl netherlands
be belgium
cn china
de germany
gb united kingdom
se sweden
es spain
fr france
us united states
hr croatia
pl poland
lt republic of lithuania
sg singapore
ch switzerland
at austria
lk sri lanka
gr greece
mt malta
iq iraq
dk denmark
hu hungary
it italy
ie ireland
tr turkey
ma morocco
pk pakistan
cw curaçao
gh ghana
vn vietnam
ro romania
au australia
mo macao
ph philippines
th thailand
kr south korea
cz czechia
cy cyprus
is iceland
pt portugal
sx sint maarten
id indonesia
tw taiwan
vi u.s. virgin islands
lu luxembourg
jo hashemite kingdom of jordan
bg bulgaria
no norway
jp japan
ae united arab emirates
ca canada
rs serbia
ua ukraine
za south africa
hk hong kong
ru russia
lv latvia
il israel
sa saudi arabia
om oman
ba bosnia and herzegovina
fi finland
nz new zealand
mm myanmar
do dominican republic
my malaysia
si slovenia
fj fiji
ss south sudan
in india
re réunion
bh bahrain
kg kyrgyzstan
kz kazakhstan
bd bangladesh
ps palestine
kh cambodia
gn guinea
dz algeria
ke kenya
tz tanzania
bs bahamas
sn senegal
mw malawi
so somalia
ls lesotho
eg egypt
la laos
rw rwanda
af afghanistan
mk north macedonia
ee estonia
ne niger
ge georgia
ng nigeria
qa qatar
np nepal
mc monaco
ml mali
ug uganda
sk slovakia
zm zambia
al albania
cd congo
lb lebanon
ly libya
bn brunei
tn tunisia
ir iran
kw kuwait
bj benin
lr liberia
lc saint lucia
ve venezuela
pr puerto rico
me montenegro
ar argentina
cv cabo verde
ao angola
sl sierra leone
by belarus
mv maldives
jm jamaica
az azerbaijan
bz belize
ci ivory coast
bi burundi
md republic of moldova
ad andorra
na namibia
ai anguilla
gp guadeloupe
sz eswatini
uz uzbekistan
mq martinique
am armenia
gg guernsey
mf saint martin
gf french guiana
cm cameroon
vc saint vincent and the grenadines
sm san marino
tg togo
bb barbados
aw aruba
zw zimbabwe
mu mauritius
sc seychelles
sr suriname
bl saint barthélemy
pa panama
pe peru
br brazil
ni nicaragua
mx mexico
bq bonaire, sint eustatius, and saba
cr costa rica
bo bolivia
co colombia
cl chile
uy uruguay
gt guatemala
et ethiopia
ec ecuador
bf burkina faso
dj djibouti
gi gibraltar
nc new caledonia
mn mongolia
gm gambia
cg republic of the congo
ye yemen
ky cayman islands
py paraguay
km comoros
mz mozambique
tj tajikistan
mg madagascar
sb solomon islands
pg papua new guinea
hn honduras
sv el salvador
li liechtenstein
bt bhutan
tt trinidad and tobago
kn st kitts and nevis
ht haiti
gy guyana
ax åland
pf french polynesia
ag antigua and barbuda
xk kosovo
ga gabon
fo faroe islands
im isle of man
yt mayotte
tc turks and caicos islands
fm federated states of micronesia
gw guinea-bissau
tl democratic republic of timor-leste
je jersey
mr mauritania
td chad
dm dominica
ms montserrat
gq equatorial guinea
va vatican city
bw botswana
gd grenada
vu vanuatu
tm turkmenistan
vg british virgin islands
sy syria
gu guam
cu cuba
sd sudan
as american samoa
pm saint pierre and miquelon
st são tomé and príncipe
cf central african republic
gl greenland
bm bermuda
ws samoa
ck cook islands
mp northern mariana islands
to tonga
io british indian ocean territory
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_1a2b3cae06d7",
    "object": "transaction",
    "created": 1571036751,
    "updated": 1571123148,
    "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_1a2b3cae06d7",
    "notify_url": "https://developer.dev/notify/",
    "status": "created",
    "metadata": [{
        "key": "external_id",
        "value": "2015486"
    }],
    "statuses": [{
        "uid": "sta_1a2b3c85a184",
        "object": "status",
        "created": 1571036751,
        "updated": 1571036751,
        "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_1a2b3cae06d7

Example Request


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

Example Response


{
    "livemode": true,
    "uid": "tra_1a2b3cae06d7",
    "object": "transaction",
    "created": 1571036751,
    "updated": 1571123148,
    "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_1a2b3cae06d7",
    "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_1a2b3cae06d7",
        "object": "transaction",
        "created": 1571036751,
        "updated": 1571123148,
        "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_1a2b3cae06d7",
        "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_1a2b3cae06d7 \
   -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
cod Congo
nl netherlands
be belgium
cn china
de germany
gb united kingdom
se sweden
es spain
fr france
us united states
hr croatia
pl poland
lt republic of lithuania
sg singapore
ch switzerland
at austria
lk sri lanka
gr greece
mt malta
iq iraq
dk denmark
hu hungary
it italy
ie ireland
tr turkey
ma morocco
pk pakistan
cw curaçao
gh ghana
vn vietnam
ro romania
au australia
mo macao
ph philippines
th thailand
kr south korea
cz czechia
cy cyprus
is iceland
pt portugal
sx sint maarten
id indonesia
tw taiwan
vi u.s. virgin islands
lu luxembourg
jo hashemite kingdom of jordan
bg bulgaria
no norway
jp japan
ae united arab emirates
ca canada
rs serbia
ua ukraine
za south africa
hk hong kong
ru russia
lv latvia
il israel
sa saudi arabia
om oman
ba bosnia and herzegovina
fi finland
nz new zealand
mm myanmar
do dominican republic
my malaysia
si slovenia
fj fiji
ss south sudan
in india
re réunion
bh bahrain
kg kyrgyzstan
kz kazakhstan
bd bangladesh
ps palestine
kh cambodia
gn guinea
dz algeria
ke kenya
tz tanzania
bs bahamas
sn senegal
mw malawi
so somalia
ls lesotho
eg egypt
la laos
rw rwanda
af afghanistan
mk north macedonia
ee estonia
ne niger
ge georgia
ng nigeria
qa qatar
np nepal
mc monaco
ml mali
ug uganda
sk slovakia
zm zambia
al albania
cd congo
lb lebanon
ly libya
bn brunei
tn tunisia
ir iran
kw kuwait
bj benin
lr liberia
lc saint lucia
ve venezuela
pr puerto rico
me montenegro
ar argentina
cv cabo verde
ao angola
sl sierra leone
by belarus
mv maldives
jm jamaica
az azerbaijan
bz belize
ci ivory coast
bi burundi
md republic of moldova
ad andorra
na namibia
ai anguilla
gp guadeloupe
sz eswatini
uz uzbekistan
mq martinique
am armenia
gg guernsey
mf saint martin
gf french guiana
cm cameroon
vc saint vincent and the grenadines
sm san marino
tg togo
bb barbados
aw aruba
zw zimbabwe
mu mauritius
sc seychelles
sr suriname
bl saint barthélemy
pa panama
pe peru
br brazil
ni nicaragua
mx mexico
bq bonaire, sint eustatius, and saba
cr costa rica
bo bolivia
co colombia
cl chile
uy uruguay
gt guatemala
et ethiopia
ec ecuador
bf burkina faso
dj djibouti
gi gibraltar
nc new caledonia
mn mongolia
gm gambia
cg republic of the congo
ye yemen
ky cayman islands
py paraguay
km comoros
mz mozambique
tj tajikistan
mg madagascar
sb solomon islands
pg papua new guinea
hn honduras
sv el salvador
li liechtenstein
bt bhutan
tt trinidad and tobago
kn st kitts and nevis
ht haiti
gy guyana
ax åland
pf french polynesia
ag antigua and barbuda
xk kosovo
ga gabon
fo faroe islands
im isle of man
yt mayotte
tc turks and caicos islands
fm federated states of micronesia
gw guinea-bissau
tl democratic republic of timor-leste
je jersey
mr mauritania
td chad
dm dominica
ms montserrat
gq equatorial guinea
va vatican city
bw botswana
gd grenada
vu vanuatu
tm turkmenistan
vg british virgin islands
sy syria
gu guam
cu cuba
sd sudan
as american samoa
pm saint pierre and miquelon
st são tomé and príncipe
cf central african republic
gl greenland
bm bermuda
ws samoa
ck cook islands
mp northern mariana islands
to tonga
io british indian ocean territory
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

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_1a2b3cae06d7/refunds

Example Request


curl https://api.onlinebetaalplatform.nl/v1/transactions/tra_1a2b3cae06d7/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_1a2b3c31c0f4",
    "object": "refund",
    "created": 1571036751,
    "updated": 1571036751,
    "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_1a2b3cae06d7/refunds

Example Request


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

Example Response


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