Merchant Onboarding API

Last updated: November 5, 2026

Note. A new version of the Merchant Onboarding API is on our roadmap for 2027.

Contact operations

Add Contact
POST/psps/{pspid}/ownedContacts
POST/divisions/{divisionsid}/ownedContacts
POST/merchants/{merchantid}/ownedContacts
Reset Contact Password
POST/contacts/{contactid}/setPassword
Get Contact
GET/contacts/{contactid}
Edit Contact
POST/contacts/{contactid}
Lock Contact
POST/contacts/{contactid}/lockContact
Unlock Contact
POST/contacts/{contactid}/unlockContact
Delete Contact
DELETE/contacts/{contactid}
Attach Contact
POST/psps/{pspid}/attachedContacts/{contactid}
POST/divisions/{divisionid}/attachedContacts/{contactid}
POST/merchants/{merchantid}/attachedContacts/{contactid}
POST/channels/{channelId}/attachedContacts/{contactid}
Detach Contact
DELETE/psps/{pspid}/attachedContacts/{contactid}
DELETE/divisions/{divisionid}/attachedContacts/{contactid}
DELETE/merchants/{merchantid}/attachedContacts/{contactid}
DELETE/channels/{channelId}/attachedContacts/{contactid}
Get Attached Contacts list
GET/psps/{pspid}/attachedContacts
GET/divisions/{divisionid}/attachedContacts
GET/merchants/{merchantid}/attachedContacts
GET/channels/{channelId}/attachedContacts
Get Owned Contacts list
GET/psps/{pspid}/ownedContacts
GET/divisions/{divisionsid}/ownedContacts
GET/merchants/{merchantid}/ownedContacts
GET/channels/{channelId}/ownedContacts

Add Contact

The call adds a new contact. The contact can be created at PSP, Division, or Merchant levels. It can be attached to any other entity at the desired level. The contact can be attached to the same entity at the same level, where it was created. For this, use the autoAttach parameter when creating the contact.

Endpoints

POST/psps/{pspid}/ownedContacts
Option 1. Add a contact using PSP ID.
POST/divisions/{divisionsid}/ownedContacts
Option 2. Add a contact using the division ID.
POST/merchants/{merchantid}/ownedContacts
Option 3. Add a contact using merchant ID.

URL parameters

pspIdrequired for option 1
[a-f 0-9]32
The ID of the PSP
divisionIdrequired for option 2
[a-f 0-9]32
The ID of the division
merchantIdrequired for option 3
[a-f 0-9]32
The ID of the merchant

Data parameters

emailrequired
It will be also the username of the contact. Use a valid e-mail address.
namerequired
First and last name
rolerequired
The role of the created contact. Must be one of these options:
  • CALLCENTER_RESTRICTED
  • ACCOUNTING_GLOBAL
  • ANALYSIS
  • CALLCENTER
  • OPERATOR
kindrequired
The kind of the created contact. Must be one of these options:
  • SEND
  • SYSTEM
  • SUPPORT
  • MOTO
  • WEB_API
  • OAUTH_APP
phoneOptional
Phone Number
oauthRedirectUrlOptional
This is required if kind:OAUTH_APP .Ex(https://pspName.test.ctpe.info/)
mobileOptional
Mobile phone number
descriptionOptional
Any description
autoAttachOptional
true|false
Set to true to attach the user to the same entity it is created. The default value is false.
languagerequired
The contact language should be a two-letter code. The available values are:
  • en (English)
  • de (German)
  • fr (French)
  • es (Spanish)
  • it (Italian)
  • ru (Russian)
  • pt (Portuguese)
  • nl (Nederlands)
  • cn (Chinese)
sendCredentialsMailOptional (default to false)
true|false Set to true to send an email upon contact creation.
sendAuthenticatorMailOptional (default to false)
true|false Set to true to send authenticator email upon contact creation.

Success response

201The entity was successfully created.
contactInfo
The contact info object.
id
[a-f0-9]32
The ID of the contact.
email
It will be also the username of the contact. Use a valid e-mail address.
username
The username of the contact. It is the e-mail address of the contact.
name
First and last name
role
The role of the created contact. Must be one of these options:
  • CALLCENTER_RESTRICTED
  • ACCOUNTING_GLOBAL
  • ANALYSIS
  • CALLCENTER
  • OPERATOR
kind
The kind of the created contact. Must be one of these options:
  • SEND
  • SYSTEM
  • SUPPORT
  • MOTO
  • WEB_API
  • OAUTH_APP
phone
Phone Number
mobile
Mobile Phone Number
description
Any description
autoAttach
true|false Set to true to attach the user to the same entity it is created. The default value is false.
state
The current state of the contact.
language
The contact language should be a two-letter code and the available values are:
  • en (English)
  • de (German)
  • fr (French)
  • es (Spanish)
  • it (Italian)
  • ru (Russian)
  • pt (Portuguese)
  • nl (Nederlands)
  • cn (Chinese)

Error response

200Used to tunnel errors. Check the error message.
POST/psps/{pspid}/ownedContacts
POST/divisions/{divisionsid}/ownedContacts
POST/merchants/{merchantid}/ownedContacts

Request sample

curl -X POST \
  'https://eu-test.oppwa.com/bip/webapi/v1/psps/{pspId}/ownedContacts' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>' \
  -H 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \
  --data-urlencode 'email=test@example.com' \
  --data-urlencode 'name=Test Account' \
  --data-urlencode 'role=CALLCENTER' \
  --data-urlencode 'kind=SEND' \
  --data-urlencode 'language=en'

Response samples

{
  "contactInfo": {
    "email": "user_1@moapi.com",
    "id": "ab12cd34ef56ab12cd34ef56ab12cd01",
    "kind": "WEB_API",
    "name": "User_Name",
    "role": "Operator",
    "state": "NEW",
    "username": "user_1@moapi.com"
  }
}

Reset Contact Password

The call resets the password for an existing contact.

Endpoints

POST/contacts/{contactid}/setPassword
Reset the contact password using the contact ID.

URL parameters

contactIdrequired
[a-f 0-9]32
The ID of the contact.

Data parameters

(no parameter allowed)

Success response

200: OKPassword successfully updated.
message
Notification about the e-mail sent to the contact, with the new password.

Error response

200: OKCheck the error message.
POST/contacts/{contactid}/setPassword

Request sample

curl -X POST \
  'https://eu-test.oppwa.com/bip/webapi/v1/contacts/{contactId}/setPassword' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "message": "A new password was sent to the contact."
}

Get Contact

The call gets information about an existing contact.

Endpoints

GET/contacts/{contactid}
Get a contact using the contact ID.

URL parameters

contactIdrequired
[a-f 0-9]32
The ID of the contact.

Data parameters

No parameters are required.

Success response

200: OKThe call was executed successfully.
contactInfo
The contact info object.
id
[a-f0-9]32
The ID of the contact.
email
It will be also the username of the contact. Use a valid e-mail address.
username
The username of the contact. It is the e-mail address of the contact.
name
First and last name
role
The role of the created contact. Must be one of the following:
  • CALLCENTER_RESTRICTED
  • ACCOUNTING_GLOBAL
  • ANALYSIS
  • CALLCENTER
  • OPERATOR
kind
The kind of the created contact. Must be one of the following:
  • SEND
  • SYSTEM
  • SUPPORT
  • MOTO
  • WEB_API
  • OAUTH_APP
phone
Phone number
mobile
Mobile phone number
description
Any description
autoAttach
true|false
Set to true to attach the user to the same entity it is created. The default value is false.
state
The current state of the contact.
language
The contact language should be a two-letter code. Available values are:
  • en (English)
  • de (German)
  • fr (French)
  • es (Spanish)
  • it (Italian)
  • ru (Russian)
  • pt (Portuguese)
  • nl (Nederlands)
  • cn (Chinese)

Error response

200: OKCheck the error message.
GET/contacts/{contactid}

Request sample

curl -X GET \
  'https://eu-test.oppwa.com/bip/webapi/v1/contacts/{contactId}' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "contactInfo": {
    "email": "user_2@moapi.com",
    "id": "ab12cd34ef56ab12cd34ef56ab12cd02",
    "kind": "WEB_API",
    "language": "en",
    "name": "User2_Name",
    "role": "Operator",
    "state": "NEW",
    "username": "user_2@moapi.com"
  }
}

Edit Contact

The call edits an existing contact.

Endpoints

POST/contacts/{contactid}
Edit a contact using the contact ID.

URL parameters

contactIdrequired
[a-f 0-9]32
The ID of the contact

Data parameters

If the request is submitted with parameters set to empty spaces - for example, email=<single space> - this will delete the previous values and leave the fields blank.
The parameters that are not included in the request are not changed. To avoid nullifying valid values, skip the parameters that do not require an update.

emailrequired
It will be also the username of the contact. Use a valid email address.
namerequired
First and last name.
rolerequired
The role of the created contact. Must be one of the following:
  • CALLCENTER_RESTRICTED
  • ACCOUNTING_GLOBAL
  • ANALYSIS
  • CALLCENTER
  • OPERATOR
kindrequired
The kind of the created contact. Must be one of the following:
  • SEND
  • SYSTEM
  • SUPPORT
  • MOTO
  • WEB_API
  • OAUTH_APP
phoneOptional
Phone number
mobileOptional
Mobile phone number
descriptionOptional
Any description
autoAttachOptional
true|false Set to true to attach the user to the same entity it is created. The default value is false.
stateOptional
The current state of the contact.
languageOptional
The contact language should be a two-letter code and the available values are:
  • en (English)
  • de (German)
  • fr (French)
  • es (Spanish)
  • it (Italian)
  • ru (Russian)
  • pt (Portuguese)
  • nl (Nederlands)
  • cn (Chinese)

Success response

200: OKThe call was executed successfully.
contactInfo
The contact info object
id
[a-f0-9]32
The ID of the contact
email
It will be also the username of the contact. Use a valid email address.
username
The username of the contact. It is the e-mail address of the contact.
name
First and last name
role
The role of the created contact. Must be one of the following:
  • CALLCENTER_RESTRICTED
  • ACCOUNTING_GLOBAL
  • ANALYSIS
  • CALLCENTER
  • OPERATOR
kind
The kind of the created contact. Must be one of the following:
  • SEND
  • SYSTEM
  • SUPPORT
  • MOTO
  • WEB_API
  • OAUTH_APP
phone
Phone number
mobile
Mobile phone number
description
Any description
autoAttach
true|false Set to true to attach the user to the same entity it is created. The default value is false.
state
The current state of the contact.
language
The contact language should be a two-letter code and the available values are:
  • en (English)
  • de (German)
  • fr (French)
  • es (Spanish)
  • it (Italian)
  • ru (Russian)
  • pt (Portuguese)
  • nl (Nederlands)
  • cn (Chinese)

Error response

200: OKCheck the error message.
POST/contacts/{contactid}

Request sample

curl -X POST \
  'https://eu-test.oppwa.com/bip/webapi/v1/contacts/{contactId}' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>' \
  -H 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \
  --data-urlencode 'email=test@example.com' \
  --data-urlencode 'name=New Name' \
  --data-urlencode 'role=ANALYSIS' \
  --data-urlencode 'kind=SEND' \
  --data-urlencode 'language=en'

Response samples

{
  "contactInfo": {
    "email": "user_2@moapi.com",
    "id": "ab12cd34ef56ab12cd34ef56ab12cd02",
    "kind": "WEB_API",
    "language": "en",
    "name": "User2_Name",
    "role": "Operator",
    "state": "NEW",
    "username": "user_2@moapi.com"
  }
}

Lock Contact

The call locks an existing contact.

Endpoints

POST/contacts/{contactid}/lockContact
Lock a contact using contact ID.

URL parameters

contactIdrequired
[a-f 0-9]32
The ID of the contact

Data parameters

No parameters are required.

Success response

200: OKThe call was executed successfully.
contactInfo
The contact info object.
id
[a-f0-9]32
The ID of the contact.
email
It will be also the username of the contact. Use a valid email address.
username
The username of the contact. It is the e-mail address of the contact.
name
First and last name.
role
The role of the created contact. Must be one of the following:
  • CALLCENTER_RESTRICTED
  • ACCOUNTING_GLOBAL
  • ANALYSIS
  • CALLCENTER
  • OPERATOR
kind
The kind of the created contact. Must be one of the following:
  • SEND
  • SYSTEM
  • SUPPORT
  • MOTO
  • WEB_API
  • OAUTH_APP
phone
Phone number
mobile
Mobile phone number
description
Any description
autoAttach
true|false Set to true to attach the user to the same entity it is created. The default value is false.
state
The current state of the contact.
language
The contact language should be a two-letter code and the available values are:
  • en (English)
  • de (German)
  • fr (French)
  • es (Spanish)
  • it (Italian)
  • ru (Russian)
  • pt (Portuguese)
  • nl (Nederlands)
  • cn (Chinese)

Error response

200: OKCheck the error message.
POST/contacts/{contactid}/lockContact

Request sample

curl -X POST \
  'https://eu-test.oppwa.com/bip/webapi/v1/contacts/{contactId}/lockContact' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "contactInfo": {
    "email": "user_4@moapi.com",
    "id": "ab12cd34ef56ab12cd34ef56ab12cd03",
    "kind": "WEB_API",
    "name": "User4_Name",
    "role": "Operator",
    "state": "LOCKED",
    "username": "user_4@moapi.com"
  }
}

Unlock Contact

The call unlocks an existing contact.

Endpoints

POST/contacts/{contactid}/unlockContact
Unlock a contact using the contact ID.

URL parameters

contactIdrequired
[a-f 0-9]32
The ID of the contact.

Data parameters

No parameters are required.

Success response

200: OKThe call was executed successfully.
contactInfo
The contact info object
id
[a-f0-9]32
The ID of the contact
email
It will be also the username of the contact. Use a valid email address.
username
The username of the contact. It is the e-mail address of the contact.
name
First and last name.
role
The role of the created contact. Must be one of the following:
  • CALLCENTER_RESTRICTED
  • ACCOUNTING_GLOBAL
  • ANALYSIS
  • CALLCENTER
  • OPERATOR
kind
The kind of the created contact. Must be one of the following:
  • SEND
  • SYSTEM
  • SUPPORT
  • MOTO
  • WEB_API
  • OAUTH_APP
phone
Phone number
mobile
Mobile phone number
description
Any description
autoAttach
true|false Set to true to attach the user to the same entity it is created. The default value is false.
state
The current state of the contact.
language
The contact language should be a two-letter code. The available values are:
  • en (English)
  • de (German)
  • fr (French)
  • es (Spanish)
  • it (Italian)
  • ru (Russian)
  • pt (Portuguese)
  • nl (Nederlands)
  • cn (Chinese)

Error response

200: OKCheck the error message.
POST/contacts/{contactid}/unlockContact

Request sample

curl -X POST \
  'https://eu-test.oppwa.com/bip/webapi/v1/contacts/{contactId}/unlockContact' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "contactInfo": {
    "email": "user_4@moapi.com",
    "id": "ab12cd34ef56ab12cd34ef56ab12cd03",
    "kind": "WEB_API",
    "name": "User4_Name",
    "role": "Operator",
    "state": "ACTIVE",
    "username": "user_4@moapi.com"
  }
}

Delete Contact

The call deletes an existing contact. The contact must be detached before deleting.

Endpoints

DELETE/contacts/{contactid}
Delete a contact using the contact Id.

URL parameters

contactIdrequired
[a-f 0-9]32
The ID of the contact.

Data parameters

No parameters are required.

Success response

200: OKThe call was executed successfully.
message
Notification about the success of the delete operation.

Error response

200: OKCheck the error message.
DELETE/contacts/{contactid}

Request sample

curl -X DELETE \
  'https://eu-test.oppwa.com/bip/webapi/v1/contacts/{contactId}' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "message": " Contact successfully deleted."
}

Attach Contact

The call attaches a contact to the desired entity.
The contact can be created at one level and then attached to another entity at another level.

Endpoints

POST/psps/{pspid}/attachedContacts/{contactid}
Option 1. Attach a contact using PSP ID.
POST/divisions/{divisionid}/attachedContacts/{contactid}
Option 2. Attach a contactusing the division ID.
POST/merchants/{merchantid}/attachedContacts/{contactid}
Option 3. Attach a contact using the merchant ID.
POST/channels/{channelId}/attachedContacts/{contactid}
Option 4. Attach a contact using the channel ID.

URL parameters

pspIdrequired for option 1
[a-f 0-9]32
The ID of the PSP.
divisionIdrequired for option 2
[a-f 0-9]32
The ID of the division.
merchantIdrequired for option 3
[a-f 0-9]32
The ID of the merchant.
channelIdrequired for option 4
[a-f 0-9]32
The ID of the channel.
contactIdrequired for all options
[a-f 0-9]32
The ID of the contact.

Data parameters

No parameters are required

Success response

200: OKThe call was executed successfully.
contactInfo
The contact info object.
id
[a-f0-9]32
The ID of the contact.
email
It will be also the username of the contact. Use a valid email address.
username
The username of the contact. It is the e-mail address of the contact.
name
First and last name
role
The role of the created contact. Must be one of the following:
  • CALLCENTER_RESTRICTED
  • ACCOUNTING_GLOBAL
  • ANALYSIS
  • CALLCENTER
  • OPERATOR
kind
The kind of the created contact. Must be one of the following:
  • SEND
  • SYSTEM
  • SUPPORT
  • MOTO
  • WEB_API
  • OAUTH_APP
phone
Phone number
mobile
Mobile phone number
description
Any description
autoAttach
true|false Set to true to attach the user to the same entity it created. The default value is false.
state
The current state of the contact.
language
The contact language should be a two-letter code. Available values are:
  • en (English)
  • de (German)
  • fr (French)
  • es (Spanish)
  • it (Italian)
  • ru (Russian)
  • pt (Portuguese)
  • nl (Nederlands)
  • cn (Chinese)

Error response

200.*.*Check the error message.
Note (2016-10-06). The call worked only for attaching the contacts at the same level of the hierarchy, which owns the contact.
POST/psps/{pspid}/attachedContacts/{contactid}
POST/divisions/{divisionid}/attachedContacts/{contactid}
POST/merchants/{merchantid}/attachedContacts/{contactid}
POST/channels/{channelId}/attachedContacts/{contactid}

Request sample

curl -X POST \
  'https://eu-test.oppwa.com/bip/webapi/v1/psps/{pspId}/attachedContacts/{contactId}' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "contactInfo": {
    "email": "user_4@moapi.com",
    "id": "ab12cd34ef56ab12cd34ef56ab12cd03",
    "kind": "WEB_API",
    "name": "User4_Name",
    "role": "Operator",
    "state": "ACTIVE",
    "username": "user_4@moapi.com"
  }
}

Detach Contact

The call allows detaching an attached contact.

Endpoints

DELETE/psps/{pspid}/attachedContacts/{contactid}
Option 1. Detach a contact using the PSP ID.
DELETE/divisions/{divisionid}/attachedContacts/{contactid}
Option 2. Detach a contactusing the division ID.
DELETE/merchants/{merchantid}/attachedContacts/{contactid}
Option 3. Detach a contact using the merchant ID.
DELETE/channels/{channelId}/attachedContacts/{contactid}
Option 4. Detach a contact using the channel ID.

URL parameters

pspIdrequired for option 1
[a-f 0-9]32
The ID of the PSP.
divisionIdrequired for option 2
[a-f 0-9]32
The ID of the division.
merchantIdrequired for option 3
[a-f 0-9]32
The ID of the merchant.
channelIdrequired for option 4
[a-f 0-9]32
The ID of the channel.
contactIdrequired for all options
[a-f 0-9]32
The ID of the contact.

Data parameters

No parameters are required.

Success response

200: OKThe call was executed successfully.
message
Notification about the success of the detach operation.

Error response

200: OKCheck the error message.
DELETE/psps/{pspid}/attachedContacts/{contactid}
DELETE/divisions/{divisionid}/attachedContacts/{contactid}
DELETE/merchants/{merchantid}/attachedContacts/{contactid}
DELETE/channels/{channelId}/attachedContacts/{contactid}

Request sample

curl -X DELETE \
  'https://eu-test.oppwa.com/bip/webapi/v1/psps/{pspId}/attachedContacts/{contactId}' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "message": "Contact successfully detached from entity."
}

Get Attached Contacts list

The call lists the information about contacts that are attached to an entity. Do not confuse it with Get Owned Contacts list.
The call Get Attached Contacts list is getting the contacts that are attached to an entity but might have been created under a different entity.

Endpoints

GET/psps/{pspid}/attachedContacts
Option 1. List the attached contacts using pspID.
GET/divisions/{divisionid}/attachedContacts
Option 2. List the attached contactsusing divisionID.
GET/merchants/{merchantid}/attachedContacts
Option 3. List the attached contactsusing merchantID.
GET/channels/{channelId}/attachedContacts
Option 4. List the attached contacts using channelID.

URL parameters

pspIdrequired for option 1
[a-f 0-9]32
The ID of the PSP.
divisionIdrequired for option 2
[a-f 0-9]32
The ID of the division.
merchantIdrequired for option 3
[a-f 0-9]32
The ID of the merchant.
channelIdrequired for option 4
[a-f 0-9]32
The ID of the channel.

Data parameters

No parameters are required.

Success response

200: OKThe call was executed successfully.
contactInfo
The contact info object.
id
[a-f0-9]32
The ID of the contact.
email
It will be also the username of the contact. Use a valid email address.
username
The username of the contact. It is the e-mail address of the contact.
name
First and last name.
role
The role of the created contact. Must be one of the following:
  • CALLCENTER_RESTRICTED
  • ACCOUNTING_GLOBAL
  • ANALYSIS
  • CALLCENTER
  • OPERATOR
kind
The kind of the created contact. Must be one of the following:
  • SEND
  • SYSTEM
  • SUPPORT
  • MOTO
  • WEB_API
  • OAUTH_APP
phone
Phone number
mobile
Mobile phone number
description
Any description
autoAttach
true|false Set to true to attach the user to the same entity it is created. The default value is false.
state
The current state of the contact.
language
The contact language should be a two-letter code. Available values are:
  • en (English)
  • de (German)
  • fr (French)
  • es (Spanish)
  • it (Italian)
  • ru (Russian)
  • pt (Portuguese)
  • nl (Nederlands)
  • cn (Chinese)

Error response

200.*.*Check the error message.
GET/psps/{pspid}/attachedContacts
GET/divisions/{divisionid}/attachedContacts
GET/merchants/{merchantid}/attachedContacts
GET/channels/{channelId}/attachedContacts

Request sample

curl -X GET \
  'https://eu-test.oppwa.com/bip/webapi/v1/psps/{pspId}/attachedContacts' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "contactList": [
    {
      "description": "",
      "email": "",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd05",
      "kind": "WEB_API",
      "mobile": "",
      "name": "MO API Admin",
      "phone": "",
      "role": "Administrator",
      "state": "ACTIVE",
      "username": "moapi.admin@email.com"
    },
    {
      "email": "user_3@moapi.com",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd06",
      "kind": "WEB_API",
      "name": "User3_Name",
      "role": "Operator",
      "state": "NEW",
      "username": "user_3@moapi.com"
    },
    {
      "email": "user_4@moapi.com",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd03",
      "kind": "WEB_API",
      "name": "User4_Name",
      "role": "Operator",
      "state": "ACTIVE",
      "username": "user_4@moapi.com"
    },
    {
      "email": "user_1@moapi.com",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd01",
      "kind": "WEB_API",
      "name": "User_Name",
      "role": "Operator",
      "state": "NEW",
      "username": "user_1@moapi.com"
    }
  ]
}

Get Owned Contacts list

The call lists details about all contacts that were created or attached at the level of an entity. Do not confuse it with Get Attached Contacts list.
The call Get Owned Contacts list is getting the contacts that were created at the level of a specific entity but might have been attached to a different entity, and the contacts that were attached to this specific entity.

Endpoints

GET/psps/{pspid}/ownedContacts
Option 1. List the owned contacts using the PSP ID.
GET/divisions/{divisionid}/ownedContacts
Option 2. List the owned contactsusing the division ID.
GET/merchants/{merchantid}/ownedContacts
Option 3. List the owned contactsusing the merchant ID.
GET/channels/{channelId}/ownedContacts
Option 4. List the owned contacts using the channel ID.

URL parameters

pspIdrequired for option 1
[a-f 0-9]32
The ID of the PSP.
divisionIdrequired for option 2
[a-f 0-9]32
The ID of the division.
merchantIdrequired for option 3
[a-f 0-9]32
The ID of the merchant.
channelIdrequired for option 4
[a-f 0-9]32
The ID of the channel.

Data parameters

No parameters are required.

Success response

200: OKThe call was executed successfully.
contactInfo
The contact info object
id
[a-f0-9]32
The ID of the contact
email
It will be also the username of the contact. Use a valid email address.
username
The username of the contact. It is the e-mail address of the contact.
name
First and last name
role
The role of the created contact. Must be one of the following:
  • CALLCENTER_RESTRICTED
  • ACCOUNTING_GLOBAL
  • ANALYSIS
  • CALLCENTER
  • OPERATOR
kind
The kind of the created contact. Must be one of the following:
  • SEND
  • SYSTEM
  • SUPPORT
  • MOTO
  • WEB_API
  • OAUTH_APP
phone
Phone number
mobile
Mobile phone number
description
Any description
autoAttach
true|false Set to true to attach the user to the same entity it is created. The default value is false.
state
The current state of the contact.
language
The contact language should be a two-letter code. Available values are:
  • en (English)
  • de (German)
  • fr (French)
  • es (Spanish)
  • it (Italian)
  • ru (Russian)
  • pt (Portuguese)
  • nl (Nederlands)
  • cn (Chinese)

Error response

200.*.*Check the error message.
GET/psps/{pspid}/ownedContacts
GET/divisions/{divisionid}/ownedContacts
GET/merchants/{merchantid}/ownedContacts
GET/channels/{channelId}/ownedContacts

Request sample

curl -X GET \
  'https://eu-test.oppwa.com/bip/webapi/v1/psps/{pspId}/ownedContacts' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "contactList": [
    {
      "description": "",
      "email": "",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd05",
      "kind": "WEB_API",
      "mobile": "",
      "name": "MO API Admin",
      "phone": "",
      "role": "Administrator",
      "state": "ACTIVE",
      "username": "moapi.admin@email.com"
    },
    {
      "email": "user_1@moapi.com",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd01",
      "kind": "WEB_API",
      "name": "User_Name",
      "role": "Operator",
      "state": "NEW",
      "username": "user_1@moapi.com"
    },
    {
      "email": "user_3@moapi.com",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd06",
      "kind": "WEB_API",
      "name": "User3_Name",
      "role": "Operator",
      "state": "NEW",
      "username": "user_3@moapi.com"
    },
    {
      "email": "user_4@moapi.com",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd03",
      "kind": "WEB_API",
      "name": "User4_Name",
      "role": "Operator",
      "state": "ACTIVE",
      "username": "user_4@moapi.com"
    }
  ]
}

Clearing Institute operations

Get Clearing Institutes list
GET/psps/{pspid}/clearingInstitutes

Get Clearing Institutes list

The call lists the information about existing clearing institutes.

  • Clearing institutes are entities defining the different acquiring connections provided by the platform.
  • The availability of a clearing institute for a specific merchant/PSP is discussed before contracts are signed. Additional clearing institutes can be made available later. The clearing institutes list, available to you, should be discussed with the account manager.

Endpoints

GET/psps/{pspid}/clearingInstitutes
List the clearing institutes via pspID

URL parameters

pspIdrequired
[a-f 0-9]32
The ID of the PSP

Data parameters

No parameters are required

Success response

200OK
country
[A-Z]2
The country of the clearing institute.
id
[a-f 0-9]32
The ID of the clearing institute.
internationalCode
[A-Z a-z 0-9], [-_ ]128
The international code of the clearing institute.
name
[A-Z a-z 0-9], [-_ ]128
The name of the clearing Institute.

Error response

200Used to tunnel errors. Check the error message.
404: Not FoundThere is an error in the URL.
GET/psps/{pspid}/clearingInstitutes

Request sample

curl -X GET \
  'https://eu-test.oppwa.com/bip/webapi/v1/psps/{pspId}/clearingInstitutes' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "clearingInstitutes": []
}

Division-level operations

Add Division
POST/psps/{pspId}/divisions
POST/entities/byName/{pspName}/divisions
Get Division
GET/divisions/{divisionId}
Edit Division
POST/divisions/{divisionId}
List Divisions
GET/psps/{pspId}/divisions
Delete Division
DELETE/divisions/{divisionId}

Add Division

The call adds a new division.

Endpoints

POST/psps/{pspId}/divisions
Option 1. Add a division using PSP ID.
POST/entities/byName/{pspName}/divisions
Option 2. Add a division using entity path.

URL parameters

pspIdrequired for option 1
[a-f 0-9]32
The ID of the PSP.
pspNamerequired for option 2
[A-Z a-z 0-9], [-_ ]256
The entity name identifying the PSP.

Data parameters

namerequired
[A-Z a-z 0-9], [-_]32
The name of the entity to be created.
customerIdOptional
[A-Z a-z 0-9], [-_ ]32
An ID value that can be retrieved later for integration.
descriptionOptional
[A-Z a-z 0-9], [-_ ]50
A description of the entity.
staterequired
Note that the default value is inherited from the parent entity. Possible values are “LIVE”, “CONNECTOR_TEST”, “INTEGRATOR_TEST”, or “DISABLED”

Success response

201: CreatedThe entity was successfully created.
id
[a-f 0-9]32
The ID of the division to be created.
divisionInfo
Object containing all fields needed to send a transaction with the same names as used in the transaction XML.
customerId
[A-Za-z 0-9], [-_ ]32
The customer ID.
description
[A-Za-z 0-9], [-_ ]50
The description.
pspId
[a-f 0-9]32
The parent PSP ID.
name
[A-Z a-z 0-9], [-_]256
The name of the division.
state
The state can be one of the values “LIVE”, “CONNECTOR_TEST”, “INTEGRATOR_TEST”, or “DISABLED”.

Error response

200.*.*Used to tunnel errors. Check the error message.
POST/psps/{pspId}/divisions
POST/entities/byName/{pspName}/divisions

Request sample

curl -X POST \
  'https://eu-test.oppwa.com/bip/webapi/v1/psps/{pspId}/divisions' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>' \
  -H 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \
  --data-urlencode 'name=New_Test_Division' \
  --data-urlencode 'state=INTEGRATOR_TEST' \
  --data-urlencode 'description=For testing purposes'

Response samples

{
  "divisionInfo": {
    "description": "First_test_Division",
    "id": "ab12cd34ef56ab12cd34ef56ab12cd67",
    "name": "moapi_Division_1",
    "pspId": "ab12cd34ef56ab12cd34ef56ab12cd68",
    "state": "LIVE"
  },
  "id": "ab12cd34ef56ab12cd34ef56ab12cd67"
}

Get Division


The call gets the information about an existing division.

Endpoints

GET/divisions/{divisionId}
Get a division using division ID.

URL parameters

divisionIdrequired
[a-f 0-9]32
The ID of the division.

Data parameters

No parameters are required.

Success response

200: OKThe request was successful.
divisionInfo
Object containing all fields needed to send a transaction with the same names as used in the transaction XML.
id
[a-f 0-9]32
The ID of the division to be viewed.
name
[A-Z a-z 0-9], [-_]256
The name of the entity to be viewed.
pspId
[a-f 0-9]32
The parent PSP ID.
state
The state can be one of the values “LIVE”, “CONNECTOR_TEST”, “INTEGRATOR_TEST”, or “DISABLED”.
customerId
[A-Z a-z 0-9], [-_ ]32
The customer ID.
description
[A-Za-z0-9], [-_ ]50
A simple description of the entity.

Error response

200.*.*Used to tunnel errors. Check the error message.
GET/divisions/{divisionId}

Request sample

curl -X GET \
  'https://eu-test.oppwa.com/bip/webapi/v1/divisions/{divisionId}' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "divisionInfo": {
    "description": "First_test_Division",
    "id": "ab12cd34ef56ab12cd34ef56ab12cd67",
    "name": "moapi_Division_1",
    "pspId": "ab12cd34ef56ab12cd34ef56ab12cd68",
    "state": "LIVE"
  }
}

Edit Division

The call allows editing the information for an existing division.

Endpoints

POST/divisions/{divisionId}
Edit the division using the division ID.

URL parameters

divisionIdrequired
[a-f 0-9]32
The ID of the division.

Data parameters

If the request is submitted with parameters set to empty spaces, for example name=<single space>, this will delete the previous values and leave the fields blank.
The parameters not included in the request are not changed. To avoid nullifying valid values, skip the parameters that do not require an update.

namerequired
[A-Z a-z 0-9], [-_]32
The name of the entity.
customerIdOptional
[A-Z a-z 0-9], [-_ ]32
An ID value that can be retrieved for integration.
descriptionOptional
[A-Z a-z 0-9], [-_ ]50
A description of the entity.
staterequired
Note that the default value is inherited from the parent entity. Possible values are “LIVE”, “CONNECTOR_TEST”, “INTEGRATOR_TEST”, or “DISABLED”

Success response

200: OKThe details of the division were updated successfully.
divisionInfo
Object containing all fields necessary to send a transaction with the same names as used in the transaction XML.
id
[a-f 0-9]32
The ID of the division.
name
[A-Z a-z 0-9], [-_]256
The name of the entity.
pspId
[a-f 0-9]32
The parent PSP ID.
state
The state can be one of the values “LIVE”, “CONNECTOR_TEST”, “INTEGRATOR_TEST”, or “DISABLED”.
customerId
[A-Z a-z 0-9], [-_ ]32
The customer ID.
description
[A-Za-z0-9], [-_ ]50
A description of the entity.

Error response

200.*.*Used to tunnel errors. Check the error message.
POST/divisions/{divisionId}

Request sample

curl -X POST \
  'https://eu-test.oppwa.com/bip/webapi/v1/divisions/{divisionId}' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>' \
  -H 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \
  --data-urlencode 'name=New_Name' \
  --data-urlencode 'state=DISABLED' \
  --data-urlencode 'description=Updated description'

Response samples

{
  "divisionInfo": {
    "description": "First_test_Division",
    "id": "ab12cd34ef56ab12cd34ef56ab12cd67",
    "name": "moapi_Division_0",
    "pspId": "ab12cd34ef56ab12cd34ef56ab12cd68",
    "state": "LIVE"
  },
  "id": "ab12cd34ef56ab12cd34ef56ab12cd67"
}

Get Divisions List

The call lists the information about existing divisions.

Endpoints

GET/psps/{pspId}/divisions
List the divisions using PSP ID.

URL parameters

pspIdrequired
[a-f 0-9]32
The ID of the PSP.

Data parameters

No parameters required.

Success response

200:OKThe request was successful.
divisionInfo
Object containing all fields necessary to send a transaction with the same names as used in the transaction XML.
id
[a-f 0-9]32
The ID of the division to be viewed.
name
[A-Z a-z 0-9], [-_]256
The name of the entity to be viewed.
pspId
[a-f 0-9]32
The parent PSP ID.
state
The state can be one of the values “LIVE”, “CONNECTOR_TEST”, “INTEGRATOR_TEST”, or “DISABLED”.
customerId
[A-Z a-z 0-9], [-_ ]32
The customer ID.
description
[A-Za-z0-9], [-_ ]50
A simple description of the entity.

Error response

200.*.*Used to tunnel errors. Check the error message.
GET/psps/{pspId}/divisions

Request sample

curl -X GET \
  'https://eu-test.oppwa.com/bip/webapi/v1/psps/{pspId}/divisions' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "divisions": [
    {
      "customerId": "id",
      "description": "A",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd70",
      "name": "moapi_division",
      "pspId": "ab12cd34ef56ab12cd34ef56ab12cd68",
      "state": "LIVE"
    },
    {
      "customerId": "id",
      "description": "A",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd71",
      "name": "moapi_division_test",
      "pspId": "ab12cd34ef56ab12cd34ef56ab12cd68",
      "state": "LIVE"
    },
    {
      "description": "First_test_Division",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd67",
      "name": "moapi_Division_0",
      "pspId": "ab12cd34ef56ab12cd34ef56ab12cd68",
      "state": "LIVE"
    }
  ]
}

Delete Division

The call sets the state of an existing division to ‘DISABLED’.
It is not possible to delete a division.

Endpoints

DELETE/divisions/{divisionId}
Delete the division using the division ID.

URL parameters

divisionIdrequired
[a-f 0-9]32
The ID of the division.

Data parameters

No parameters are required.

Success response

200: OKThe request was successful.

Error response

200Used to tunnel errors. Check the error message.
DELETE/divisions/{divisionId}

Request sample

curl -X DELETE \
  'https://eu-test.oppwa.com/bip/webapi/v1/divisions/{divisionId}' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{}

Merchant-level operations

Add Merchant
POST/divisions/{divisonId}/merchants
POST/entities/byName/{pspName}/{divisionName}/merchants
Get Merchant
GET/merchants/{merchantId}
Edit Merchant
POST/merchants/{merchantId}
List Merchants
GET/divisions/{divisionId}/merchants
GET/psps/{pspId}/merchants
Delete Merchant
DELETE/merchants/{merchantId}

Add Merchant

The call adds a new merchant.

Endpoints

POST/divisions/{divisionId}/merchants
Option 1. Add a merchant using division ID.
POST/entities/byName/{pspName}/{divisionName}/merchants
Option 2. Add a merchant using entity path.

URL parameters

divisionIdrequired for option 1
[a-f 0-9]32
The ID of the division.
pspNamerequired for option 2
[A-Z a-z 0-9], [-_]256
The entity name identifying the PSP.
divisionNamerequired for option 2
[A-Z a-z 0-9], [-_]32
The entity name identifying the division.

Data parameters

namerequired
[A-Z a-z 0-9], [-_]256
The name of the entity to be created.
customerIdOptional
[A-Z a-z 0-9], [-_ ]32
An ID value that can be retrieved later to integrate.
descriptionOptional
[A-Z a-z 0-9], [-_ ]50
A simple description of the entity.
staterequired
Note that the default value is inherited from the parent entity. Possible values are “LIVE”, “CONNECTOR_TEST”, “INTEGRATOR_TEST”, or “DISABLED”.

Success response

201: CreatedEntity was successfully created.
merchantInfo
Object containing all fields necessary to send a transaction with the same names as used in the transaction XML.
id
[a-f 0-9]32
The ID of the merchant.
name
[A-Z a-z 0-9], [-_]256
The name of the entity to be created.
divisionId
[a-f 0-9]32
The parent division ID.
state
The state can be one of the values “LIVE”, “CONNECTOR_TEST”, “INTEGRATOR_TEST”, or “DISABLED”.
customerId
[A-Z a-z 0-9], [-_ ]32
The customer ID.
description
[A-Za-z0-9], [-_ ]50
A simple description of the entity.
secret
Legacy. Not used anymore.

Error response

200.*.*Used to tunnel errors. Check the error message.
POST/divisions/{divisionId}/merchants
POST/entities/byName/{pspName}/{divisionName}/merchants

Request sample

curl -X POST \
  'https://eu-test.oppwa.com/bip/webapi/v1/divisions/{divisionId}/merchants' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>' \
  -H 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \
  --data-urlencode 'name=New_Test_Merchant' \
  --data-urlencode 'state=INTEGRATOR_TEST' \
  --data-urlencode 'description=A new merchant'

Response samples

{
  "id": "ab12cd34ef56ab12cd34ef56ab12cd72",
  "merchantInfo": {
    "description": "test_Merchant_1",
    "divisionId": "ab12cd34ef56ab12cd34ef56ab12cd67",
    "id": "ab12cd34ef56ab12cd34ef56ab12cd72",
    "name": "moapi_merchant_0",
    "secret": "<secret>",
    "state": "LIVE"
  }
}

Get Merchant


The call gets information about an existing merchant.

Endpoints

GET/merchants/{merchantId}
Get a merchant using merchant ID.

URL parameters

merchantIdrequired
[a-f 0-9]32
The ID of the merchant.

Data parameters

No parameters required.

Success response

200: OKThe request was successful.
merchantInfo
Object containing all fields necessary to send a transaction with the same names as used in the transaction XML.
id
[a-f 0-9]32
The ID of the merchant to be viewed.
name
[A-Z a-z 0-9], [-_]256
The name of the entity to be viewed.
divisionId
[a-f 0-9]32
The parent division ID.
state
The state can be one of the values “LIVE”, “CONNECTOR_TEST”, “INTEGRATOR_TEST”, or “DISABLED”.
customerId
[A-Z a-z 0-9], [-_ ]32
The customer ID.
description
[A-Za-z0-9], [-_ ]50
A simple description of the entity.
secret
Legacy. Not used anymore.

Error response

200.*.*Used to tunnel errors. Check the error message.
GET/merchants/{merchantId}

Request sample

curl -X GET \
  'https://eu-test.oppwa.com/bip/webapi/v1/merchants/{merchantId}' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "merchantInfo": {
    "description": "test_Merchant_1",
    "divisionId": "ab12cd34ef56ab12cd34ef56ab12cd67",
    "id": "ab12cd34ef56ab12cd34ef56ab12cd72",
    "name": "moapi_merchant_0",
    "secret": "<secret>",
    "state": "LIVE"
  }
}

Edit Merchant

The call edits the information for an existing merchant.

Endpoints

POST/merchants/{merchantId}
Edit the merchant using merchant ID.

URL parameters

merchantIdrequired
[a-f 0-9]32
The ID of the merchant.

Data parameters

If the request is submitted with parameters set to empty spaces, for example, name=<single space>, this deletes the previous values and leaves the fields blank.
The parameters not included in the request are not changed. To avoid nullifying valid values, skip parameters that do not require an update.

namerequired
[A-Z a-z 0-9], [-_]32
The name of the entity.
customerIdOptional
[A-Z a-z 0-9], [-_ ]32
An ID value that can be retrieved at a later point in time to integrate.
descriptionOptional
[A-Z a-z 0-9], [-_ ]50
A simple description of the entity.
staterequired
Note that the default value is inherited from the parent entity. Possible values are “LIVE”, “CONNECTOR_TEST”, “INTEGRATOR_TEST”, or “DISABLED”.

Success response

200: OKThe details of the merchant were updated successfully.
merchantInfo
Object containing all fields necessary to send a transaction with the same names as used in the transaction XML.
id
[a-f 0-9]32
The ID of the merchant to be edited.
name
[A-Z a-z 0-9], [-_]256
The name of the entity to be edited.
divisionId
[a-f 0-9]32
The parent division ID.
state
The state can be one of the values “LIVE”, “CONNECTOR_TEST”, “INTEGRATOR_TEST”, or “DISABLED”.
customerId
[A-Z a-z 0-9], [-_ ]32
The customer ID.
description
[A-Za-z0-9], [-_ ]50
A simple description of the entity.
secret
Legacy. No longer used.

Error response

200.*.*Used to tunnel errors. Check the error message.
POST/merchants/{merchantId}

Request sample

curl -X POST \
  'https://eu-test.oppwa.com/bip/webapi/v1/merchants/{merchantId}' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>' \
  -H 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \
  --data-urlencode 'name=New_Merchant_Name' \
  --data-urlencode 'state=INTEGRATOR_TEST' \
  --data-urlencode 'description=A new description'

Response samples

{
  "id": "ab12cd34ef56ab12cd34ef56ab12cd72",
  "merchantInfo": {
    "description": "test_Merchant_0",
    "divisionId": "ab12cd34ef56ab12cd34ef56ab12cd67",
    "id": "ab12cd34ef56ab12cd34ef56ab12cd72",
    "name": "moapi_merchant_0",
    "secret": "<secret>",
    "state": "LIVE"
  }
}

Get Merchants List

The call allows listing information about existing merchants.

Endpoints

GET/divisions/{divisionId}/merchants
Option 1. List the merchants using division ID.
GET/psps/{pspId}/merchants
Option 2. List the merchants using the PSP ID.

URL parameters

divisionIdrequired for option 1
[a-f 0-9]32
The ID of the division.
pspIdrequired for option 2
[a-f 0-9]32
The ID of the PSP.

Data parameters

No parameters required.

Success response

200: OKThe request was successful.
merchantInfo
Object containing all fields necessary to send a transaction with the same names as used in the transaction XML.
id
[a-f 0-9]32
The ID of the merchant to be listed.
name
[A-Z a-z 0-9], [-_]256
The name of the entity to be listed.
divisionId
[a-f 0-9]32
The parent division ID.
state
The state can be one of the values “LIVE”, “CONNECTOR_TEST”, “INTEGRATOR_TEST”, or “DISABLED”.
customerId
[A-Z a-z 0-9], [-_ ]32
The customer ID.
description
[A-Za-z0-9], [-_ ]50
A simple description of the entity.
secret
Legacy. No longer used.

Error response

200.*.*Used to tunnel errors. Check the error message.
GET/divisions/{divisionId}/merchants
GET/psps/{pspId}/merchants

Request sample

curl -X GET \
  'https://eu-test.oppwa.com/bip/webapi/v1/divisions/{divisionId}/merchants' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "merchants": [
    {
      "description": "test_Merchant_4",
      "divisionId": "ab12cd34ef56ab12cd34ef56ab12cd67",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd74",
      "name": "moapi_merchant_4",
      "secret": "<secret>",
      "state": "LIVE"
    },
    {
      "description": "test_Merchant_3",
      "divisionId": "ab12cd34ef56ab12cd34ef56ab12cd67",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd75",
      "name": "moapi_merchant_3",
      "secret": "<secret>",
      "state": "LIVE"
    },
    {
      "description": "test_Merchant_2",
      "divisionId": "ab12cd34ef56ab12cd34ef56ab12cd67",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd76",
      "name": "moapi_merchant_2",
      "secret": "<secret>",
      "state": "LIVE"
    },
    {
      "description": "test_Merchant_1",
      "divisionId": "ab12cd34ef56ab12cd34ef56ab12cd67",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd72",
      "name": "moapi_merchant_0",
      "secret": "<secret>",
      "state": "LIVE"
    }
  ]
}

Delete Merchant

The call sets the state of an existing merchant to ‘DISABLED’.
It is not possible to delete a merchant.

Endpoints

DELETE/merchants/{merchantId}
Delete the merchant using merchant ID.

URL parameters

merchantIdrequired
[a-f 0-9]32
The ID of the merchant.

Data parameters

No parameters are required.

Success response

200: OKThe request was successful.

Error response

200.*.*Used to tunnel errors. Check the error message.
DELETE/merchants/{merchantId}

Request sample

curl -X DELETE \
  'https://eu-test.oppwa.com/bip/webapi/v1/merchants/{merchantId}' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "merchantInfo": {
    "description": "test_Merchant_4",
    "divisionId": "ab12cd34ef56ab12cd34ef56ab12cd67",
    "id": "ab12cd34ef56ab12cd34ef56ab12cd74",
    "name": "moapi_merchant_4",
    "secret": "<secret>",
    "state": "DISABLED"
  }
}

Channel-level operations

Add Channel
POST/merchants/{merchantId}/channels
POST/entities/byName/{pspName}/{divisionName}/{name}/channels
Get Channel
GET/channels/{channelId}
Edit Channel
POST/channels/{channelId}
List Channels
GET/merchants/{merchantId}/channels
Delete Channel
DELETE/channels/{channelId}

Add Channel

The call adds a new channel.

Endpoints

POST/merchants/{merchantId}/channels
Option 1. Add a channel using merchant ID.
POST/entities/byName/{pspName}/{divisionName}/{name}/channels
Option 2. Add a channel using entity path.

URL parameters

merchantIdrequired for option 1
[a-f 0-9]32
The ID of the merchant.
pspNamerequired for option 2
[A-Z a-z 0-9], [-_]256
The entity name identifying the PSP.
divisionNamerequired for option 2
[A-Z a-z 0-9], [-_]32
The entity name identifying the division.
namerequired for option 2
[A-Za-z0-9], [-_]32
The entity name identifying the channel.

Data parameters

namerequired
[A-Z a-z 0-9], [-_]32
The name of the entity to be created.
customerIdOptional
[A-Z a-z 0-9], [-_ ]32
An ID value that can be retrieved later to simplify integration.
descriptionOptional
[A-Z a-z 0-9], [-_ ]50
A simple description of the entity.
staterequired
Note that the default value is inherited from the parent entity. Possible values are “LIVE”, “CONNECTOR_TEST”, “INTEGRATOR_TEST”, or “DISABLED”.

Success response

201: CreatedEntity was successfully created.
id
[a-f 0-9]32
The ID of the channel.
accessToken
Access token that should be sent for transaction processing.
channelInfo
Object containing all fields necessary to send a transaction with the same names as used in the transaction XML.
type
Currently always equals “MERCHANT”.
channel
[a-f 0-9]32
The channel ID (identical to the ID field above).
sender
[a-f 0-9]32
Identical to the merchant ID.
secret
Legacy. No longer used.
login
[a-f 0-9]32
The ID of the XML user (called “USER LOGIN” in BIP).
pwd
[A-Z a-z 0-9]24
The password of the XML user (called “USER PWD” in BIP).
state
The state can be one of the values “LIVE”, “CONNECTOR_TEST”, “INTEGRATOR_TEST”, or “DISABLED”.
customerId
[A-Z a-z 0-9], [-_ ]32
The customer ID.
description
[A-Z a-z 0-9], [-_ ]50
The description of the channel.

Error response

200.*.*Used to tunnel errors. Check the error message.
error
Error marker and container for the following field.
message
Human readable description of the error.
POST/merchants/{merchantId}/channels
POST/entities/byName/{pspName}/{divisionName}/{name}/channels

Request sample

curl -X POST \
  'https://eu-test.oppwa.com/bip/webapi/v1/merchants/{merchantId}/channels' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>' \
  -H 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \
  --data-urlencode 'name=Test_Channel_Name' \
  --data-urlencode 'state=INTEGRATOR_TEST' \
  --data-urlencode 'description=Channel description'

Response samples

{
  "channelInfo": {
    "accessToken": "<access-token>",
    "channel": "ab12cd34ef56ab12cd34ef56ab12cd78",
    "description": "moapi_Channel_1",
    "login": "ab12cd34ef56ab12cd34ef56ab12cd79",
    "name": "moapi_Channel_0",
    "pwd": "<password>",
    "secret": "<secret>",
    "sender": "ab12cd34ef56ab12cd34ef56ab12cd72",
    "state": "LIVE",
    "type": "MERCHANT"
  },
  "id": "ab12cd34ef56ab12cd34ef56ab12cd78"
}

Get Channel


The call gets information about an existing channel.

Endpoints

GET/channels/{channelId}
Get a channel using channel ID.

URL parameters

channelIdrequired
[a-f 0-9]32
The ID of the channel.

Data parameters

No parameters required.

Success response

200: OKThe request was successful.
id
[a-f 0-9]32
The ID of the channel.
channelInfo
Object containing all fields necessary to send a transaction with the same names as used in the transaction XML.
type
Currently always equals “MERCHANT”.
channel
[a-f 0-9]32
The channel ID (identical to the ID field above).
sender
[a-f 0-9]32
Identical to the merchant ID.
secret
Legacy. No longer used.
login
[a-f 0-9]32
The ID of the XML user (called “USER LOGIN” in BIP).
pwd
[A-Z a-z 0-9]24
The password of the XML user (called “USER PWD” in BIP).
state
The state can be one of the values “LIVE”, “CONNECTOR_TEST”, “INTEGRATOR_TEST”, or “DISABLED”.
customerId
[A-Z a-z 0-9], [-_ ]32
The customer ID.
description
[A-Z a-z 0-9], [-_ ]50
The description of the channel.

Error response

200.*.*Used to tunnel errors. Check the error message.
GET/channels/{channelId}

Request sample

curl -X GET \
  'https://eu-test.oppwa.com/bip/webapi/v1/channels/{channelId}' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "channelInfo": {
    "accessToken": "<access-token>",
    "channel": "ab12cd34ef56ab12cd34ef56ab12cd78",
    "description": "moapi_Channel_1",
    "login": "ab12cd34ef56ab12cd34ef56ab12cd79",
    "name": "moapi_Channel_0",
    "pwd": "<password>",
    "secret": "<secret>",
    "sender": "ab12cd34ef56ab12cd34ef56ab12cd72",
    "state": "LIVE",
    "type": "MERCHANT"
  }
}

Edit Channel

The call edits the information for an existing channel.

Endpoints

POST/channels/{channelId}
Edit the channel using channel ID.

URL parameters

channelIdrequired
[a-f 0-9]32
The ID of the channel.

Data parameters

If the request is submitted with parameters set to empty spaces, for example, name=<single space>, this deletes the previous values and leaves the fields blank.
The parameters not included in the request are not changed. To avoid nullifying valid values, skip the parameters that do not require an update.

namerequired
[A-Z a-z 0-9], [-_]32
The name of the entity.
customerIdOptional
[A-Z a-z 0-9], [-_ ]32
An ID value that can be retrieved at a later point in time to simply integration.
descriptionOptional
[A-Z a-z 0-9], [-_ ]50
A simple description of the entity.
staterequired
Note that the default value is inherited from the parent entity. Possible values are “LIVE”, “CONNECTOR_TEST”, “INTEGRATOR_TEST”, or “DISABLED”.

Success response

200: OKThe details of the channel were updated successfully.
id
[a-f 0-9]32
The ID of the channel.
channelInfo
Object containing all fields necessary to send a transaction with the same names as used in the transaction XML.
type
Currently always equals “MERCHANT”.
channel
[a-f 0-9]32
The channel ID (identical to the ID field above).
sender
[a-f 0-9]32
Identical to the merchant ID.
secret
Old legacy parameter - disregard.
login
[a-f 0-9]32
The id of the XML user (called “USER LOGIN” in BIP).
pwd
[A-Z a-z 0-9]24
The password of the XML user (called “USER PWD” in BIP).
state
The state can be one of the values “LIVE”, “CONNECTOR_TEST”, “INTEGRATOR_TEST”, or “DISABLED”.
customerId
[A-Z a-z 0-9], [-_ ]32
The customer ID.
description
[A-Z a-z 0-9], [-_ ]50
The description of the channel.

Error response

200.*.*Used to tunnel errors. Check the error message.
POST/channels/{channelId}

Request sample

curl -X POST \
  'https://eu-test.oppwa.com/bip/webapi/v1/channels/{channelId}' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>' \
  -H 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \
  --data-urlencode 'name=New_Channel_Name' \
  --data-urlencode 'state=INTEGRATOR_TEST' \
  --data-urlencode 'description=New channel description'

Response samples

{
  "channelInfo": {
    "accessToken": "<access-token>",
    "channel": "ab12cd34ef56ab12cd34ef56ab12cd78",
    "description": "moapi_Channel_0",
    "login": "ab12cd34ef56ab12cd34ef56ab12cd79",
    "name": "moapi_Channel_0",
    "pwd": "<password>",
    "secret": "<secret>",
    "sender": "ab12cd34ef56ab12cd34ef56ab12cd72",
    "state": "LIVE",
    "type": "MERCHANT"
  },
  "id": "ab12cd34ef56ab12cd34ef56ab12cd78"
}

Get Channels List

The call allows listing information about existing channels.

Endpoints

GET/merchants/{merchantId}/channels
List the channels using merchant ID.

URL parameters

merchantIdrequired
[a-f 0-9]32
The ID of the merchant.

Data parameters

No parameters are required.

Success response

200: OKThe request was successful.
id
[a-f 0-9]32
The ID of the channel.
channelInfo
Object containing all fields necessary to send a transaction with the same names as used in the transaction XML.
type
Currently always equals “MERCHANT”.
channel
[a-f 0-9]32
The channel ID (identical to the ID field above).
sender
[a-f 0-9]32
Identical to the merchant ID.
secret
Legacy parameter. No longer used.
login
[a-f 0-9]32
The ID of the XML user (called “USER LOGIN” in BIP).
pwd
[A-Z a-z 0-9]24
The password of the XML user (called “USER PWD” in BIP).
state
The state can be one of the values “LIVE”, “CONNECTOR_TEST”, “INTEGRATOR_TEST”, or “DISABLED”.
customerId
[A-Z a-z 0-9], [-_ ]32
The customer ID.
description
[A-Z a-z 0-9], [-_ ]50
The description of the channel.

Error response

200.*.*Used to tunnel errors. Check the error message.
GET/merchants/{merchantId}/channels

Request sample

curl -X GET \
  'https://eu-test.oppwa.com/bip/webapi/v1/merchants/{merchantId}/channels' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "channels": [
    {
      "accessToken": "<access-token>",
      "channel": "ab12cd34ef56ab12cd34ef56ab12cd78",
      "description": "moapi_Channel_1",
      "login": "ab12cd34ef56ab12cd34ef56ab12cd79",
      "name": "moapi_Channel_0",
      "pwd": "<password>",
      "secret": "<secret>",
      "sender": "ab12cd34ef56ab12cd34ef56ab12cd72",
      "state": "LIVE",
      "type": "MERCHANT"
    },
    {
      "accessToken": "<access-token>",
      "channel": "ab12cd34ef56ab12cd34ef56ab12cd81",
      "description": "moapi_Channel_1",
      "login": "ab12cd34ef56ab12cd34ef56ab12cd79",
      "name": "moapi_Channel_1",
      "pwd": "<password>",
      "secret": "<secret>",
      "sender": "ab12cd34ef56ab12cd34ef56ab12cd72",
      "state": "LIVE",
      "type": "MERCHANT"
    },
    {
      "accessToken": "<access-token>",
      "channel": "ab12cd34ef56ab12cd34ef56ab12cd82",
      "description": "moapi_Channel_2",
      "login": "ab12cd34ef56ab12cd34ef56ab12cd79",
      "name": "moapi_Channel_2",
      "pwd": "<password>",
      "secret": "<secret>",
      "sender": "ab12cd34ef56ab12cd34ef56ab12cd72",
      "state": "LIVE",
      "type": "MERCHANT"
    }
  ]
}

Delete Channel

This sets the state of an existing channel to ‘DISABLED’. It is not possible to delete a channel.

Endpoints

DELETE/channels/{channelId}
Delete the channel using channel ID.

URL parameters

channelIdrequired
[a-f 0-9]32
The ID of the channel.

Data parameters

No parameters are required.

Success response

200: OKThe request was successful.
id
[a-f 0-9]32
The ID of the channel.
channelInfo
Object containing all fields necessary to send a transaction with the same names as used in the transaction XML.
type
Currently always equals “MERCHANT”.
channel
[a-f 0-9]32
The channel ID (identical to the ID field above).
sender
[a-f 0-9]32
Identical to the merchant ID.
secret
Legacy. No longer used.
login
[a-f 0-9]32
The ID of the XML user (called “USER LOGIN” in BIP).
pwd
[A-Z a-z 0-9]24
The password of the XML user (called “USER PWD” in BIP).
state
The state can be one of the values “LIVE”, “CONNECTOR_TEST”, “INTEGRATOR_TEST”, or “DISABLED”.
customerId
[A-Z a-z 0-9], [-_ ]32
The customer ID.
description
[A-Z a-z 0-9], [-_ ]50
The description of the channel.

Error response

200.*.*Used to tunnel errors. Check the error message.
DELETE/channels/{channelId}

Request sample

curl -X DELETE \
  'https://eu-test.oppwa.com/bip/webapi/v1/channels/{channelId}' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "channelInfo": {
    "accessToken": "<access-token>",
    "channel": "ab12cd34ef56ab12cd34ef56ab12cd83",
    "description": "moapi_Channel_5",
    "login": "ab12cd34ef56ab12cd34ef56ab12cd84",
    "name": "moapi_Channel_5",
    "pwd": "<password>",
    "secret": "<secret>",
    "sender": "ab12cd34ef56ab12cd34ef56ab12cd74",
    "state": "DISABLED",
    "type": "MERCHANT"
  }
}

Merchant Account operations

Add Merchant Account
POST/psps/{pspid}/ownedMerchantAccounts
POST/divisions/{divisionsid}/ownedMerchantAccounts
POST/merchants/{merchantid}/ownedMerchantAccounts
Get Merchant Account
GET/merchantAccounts/{merchantAccountId}
Edit Merchant Account
POST/merchantAccounts/{merchantAccountId}
Delete Merchant Account
DELETE/merchantAccounts/{merchantAccountId}
Attach Merchant Account
POST/psps/{pspid}/attachedMerchantAccounts
POST/divisions/{divisionid}/attachedMerchantAccounts
POST/merchants/{merchantid}/attachedMerchantAccounts
POST/channels/{channelId}/attachedMerchantAccounts
Edit Attached Merchant Account
POST/attachedMerchantAccounts/{attachedMerchantAccountId}
Detach Merchant Account
DELETE/attachedMerchantAccounts/{attachedMerchantAccountId}
Get Attached Merchant Account list
GET/psps/{pspid}/attachedMerchantAccounts
GET/divisions/{divisionid}/attachedMerchantAccounts
GET/merchants/{merchantid}/attachedMerchantAccounts
GET/channels/{channelid}/attachedMerchantAccounts
Detach All Attached Merchant Accounts
DELETE/psps/{pspid}/attachedMerchantAccounts
DELETE/divisions/{divisionid}/attachedMerchantAccounts
DELETE/merchants/{merchantid}/attachedMerchantAccounts
DELETE/channels/{channelid}/attachedMerchantAccounts
Get Owned Merchant Account list
GET/psps/{pspid}/ownedMerchantAccounts
GET/divisions/{divisionsid}/ownedMerchantAccounts
GET/merchants/{merchantid}/ownedMerchantAccounts
GET/channels/{channelid}/ownedMerchantAccounts
Delete All Owned Merchant Accounts
DELETE/psps/{pspid}/ownedMerchantAccounts
DELETE/divisions/{divisionsid}/ownedMerchantAccounts
DELETE/merchants/{merchantid}/ownedMerchantAccounts
DELETE/channels/{channelid}/ownedMerchantAccounts
3D Secure Setup
POST/merchantAccounts/{merchantAccountId}
POST+
POST/merchants/*/setting
Generate EBICS PDF file
POST/merchantAccounts/{merchantAccountId}/ebics

Add Merchant Account

The call adds a Merchant Account. The Merchant Account is uniquely associated with a Clearing Institute. Depending on the Clearing Institute selected, the field mapping will be different for the Merchant Account Configuration.
The complete mapping is presented in 02 Merchant Account Configuration by Clearing Institute. The Merchant Account can be created at PSP, Division or Merchant levels. Then, it can be attached to any other entity, at the desired level. The contact can be attached to the same entity, at the same level, where it was created.

Endpoints

POST/psps/{pspid}/ownedMerchantAccounts
Option 1. Add a Merchant Account using pspID.
POST/divisions/{divisionsid}/ownedMerchantAccounts
Option 2. Add a Merchant Account using divisionID.
POST/merchants/{merchantid}/ownedMerchantAccounts
Option 3. Add a Merchant Account using merchantID.
POST/channels/{channelid}/ownedMerchantAccounts
Option 4. Add a Merchant Account using channelID.

URL parameters

pspIdrequired for option 1
[a-f 0-9]32
The ID of the PSP.
divisionIdrequired for option 2
[a-f 0-9]32
The ID of the division.
merchantIdrequired for option 3
[a-f 0-9]32
The ID of the merchant.

Data parameters

name
[A-Z a-z 0-9], [-_]256
The name of the merchant account.
state
Possible values are "LIVE", "CLOSED", "TEST" or "DISABLED".
clearingInstituteIdclearingInstituteName
[a-f 0-9]32
The ID or name of the clearing institute, as listed in the GET response, querying the clearing institute list. See 03 Clearing Institute operations for the list of operations and the merchant account configuration per clearing institute.
iban
[A-Z a-z 0-9], [-_ ]32
–
key
[A-Z a-z 0-9], [-_ ]500
–
terminalId
anyany
–
password
[A-Z a-z 0-9], [-_ ]128
–
username
[A-Z a-z 0-9], [-_ ]128
–
merchantCategory
Possible values are: RETAIL, SERVICES, AIRLINE, HOTEL, TRAVEL, GAMING, GAMBLING, DIGITAL_CONTENT, AUCTION, ADULT, UTILITIES, E_TICKETING or ONLINE_FINANCIAL
transactionCategory
Possible values are: ANY, MOTO, ECOMMERCE, EWALLET
cvvInstruction
–
cvvRejectionPolicy
–
avsCheckActive
TRUE or FALSE
avsRejectionPolicy
Possible values are: A, Z, N, U
avsReviewPolicy
Possible values are: A, Z, N, U
debitAdviceProcedure
Possible values are: DA or DD
recurringCode
Possible values are: NONE, RECURRING, INSTALLMENT
supports3DSecure
TRUE or FALSE
merchant3DName
anyany
–
merchant3DUrl
anyany
–
merchantIsoCountryCode
–
visaMerchantId
[A-Z]2
–
visaMerchantAcquirerBin
–
masterMerchantId
–
masterMerchantAcquirerBin
–
amexMerchantId
–
amexMerchantAcquirerBin
–
bcmcMerchantId
–
bcmcMerchantAcquirerBin
–
dinersMerchantId
–
dinersMerchantAcquirerBin
–
dinersMerchantPwd
–
jcbMerchantId
–
jcbMerchantAcquirerBin
–
bankfileGenerationPattern
[A-Z a-z 0-9], [-_:@ ]20
Bank files can be generated weekly or daily.
  • Weekly bank files are generated only one time during the selected day of the week.
    For example, MONDAY@13:00 UTC will generate one bank file on Monday at 13:00 UTC.

  • Daily bank files can be generated up to three times a day.
    For example,
    DAILY@5:00 UTC will generate one bank file daily at 5:00 UTC.
    DAILY@5:00 UTC+DAILY@13:00 UTC will generate two bank files daily at 5:00 and 13:00 UTC.
    DAILY@5:00 UTC+DAILY@13 UTC+DAILY@18:00 UTC will generate three bank files daily at 5:00, 13:00, and 18:00 UTC.
velocityDispachingActive
TRUE or FALSE
velocityDispatchingSetting
[A-Z a-z 0-9], [-_; ]32
{Maximum number of Tx};{Maximum volume};{within};{HOUR|DAY|WEEK|MONTH|YEAR} For example, 12;11;2;DAY
ticketSizeDispatchingActive
TRUE or FALSE
ticketSizeDispatchingSetting
[A-Z a-z 0-9], [-_; ]32
{Minimum ticket size};{Maximum ticket size} For example, 2;10
recurringDispatchingSetting
ALL: All shoppers TRUE: Recurring shoppers FALSE: First-time shoppers
shopperDispatchingSetting
ALL: All shoppers TRUE: Recurring shoppers FALSE: First-time shoppers
shopperDispatchingScope
PSP, DIVISION, MERCHANT, or CHANNEL
shopperDispatchingValidity
In days
paymentDispatchingSetting
ALL, CREDITS, DEBITS or ONLINE_TRANSFER
pendingTimeoutInMins
[0-9]
Define time in minutes when this payment request from Consumer should timeout.
pendingForAcquirerTimeoutInMins
[0-9]
Define time in minutes when the final payment status request from Acquirer should timeout.
uploadUser
–
uploadPassword
–
connectorSpecificParameter.&lt;parameter&gt;
[A-Z a-z 0-9], [-_ ]any
Acceptor data parameters are specific to each connector/clearing institute. For possible values please consult the connector integration sheet.
visaAcquirerMerchantId
visa acquirer merchant id
masterAcquirerMerchantId
Mastercard acquirer merchant id
amexAcquirerMerchantId
Amex acquirer merchant id

Success response

201: CreatedEntity was successfully created.
id
[a-f 0-9]32
The ID of the entity at which level the Merchant Account will be created.
merchantAccount
Object containing all fields necessary to send a transaction with the same names as used in the transaction XML.
name
[A-Z a-z 0-9], [-_]256
The name of the merchant account.
state
Possible values are "LIVE", "CLOSED", "TEST" or "DISABLED".
clearingInstitute
[A-Z a-z 0-9], [-_ ]32
The ID or name of the clearing institute, as listed in the GET response, querying the clearing institute list. See 03 Clearing Institute operations for the list of operations and the merchant account configuration per clearing institute.
iban
[A-Z a-z 0-9], [-_ ]32
–
key
[A-Z a-z 0-9], [-_ ]500
–
terminalId
anyany
verw
password
[A-Z a-z 0-9], [-_ ]128
–
username
[A-Z a-z 0-9], [-_ ]128
–
merchantId
[a-f 0-9]32
The ID of the merchant.
merchantName
[A-Z a-z 0-9], [-_ ]32
The entity name to identify the merchant.
merchantCategory
Possible values are: RETAIL, SERVICES, AIRLINE, HOTEL, TRAVEL, GAMING, GAMBLING, DIGITAL_CONTENT, AUCTION, ADULT, UTILITIES, E_TICKETING or ONLINE_FINANCIAL
transactionCategory
Possible values are: ANY, MOTO, ECOMMERCE, EWALLET
cvvInstruction
–
cvvRejectionPolicy
–
avsCheckActive
TRUE or FALSE
avsRejectionPolicy
Possible values are: A, Z, N, U
avsReviewPolicy
Possible values are: A, Z, N, U
debitAdviceProcedure
Possible values are: DA or DD
recurringCOde
Possible values are: NONE, RECURRING, INSTALLMENT
supports3DSecure
TRUE or FALSE
merchant3DName
anyany
–
merchant3DUrl
anyany
–
merchantIsoCountryCode
–
visaMerchantId
[A-Z]2
–
visaMerchantAcquirerBin
–
masterMerchantId
–
masterMerchantAcquirerBin
–
amexMerchantId
–
amexMerchantAcquirerBin
–
bcmcMerchantId
–
bcmcMerchantAcquirerBin
–
dinersMerchantId
–
dinersMerchantAcquirerBin
–
dinersMerchantPwd
–
jcbMerchantId
–
jcbMerchantAcquirerBin
–
bankfileGenerationPattern
[A-Z a-z 0-9], [-_ ]20
Bank files can be generated weekly or daily.
  • Weekly bank files are generated only one time during the selected day of the week.
    For example, MONDAY@13:00 UTC will generate one bank file on Monday at 13:00 UTC.

  • Daily bank files can be generated up to three times a day.
    For example,
    DAILY@5:00 UTC will generate one bank file daily at 5:00 UTC.
    DAILY@5:00 UTC+DAILY@13:00 UTC will generate two bank files daily at 5:00 and 13:00 UTC.
    DAILY@5:00 UTC+DAILY@13 UTC+DAILY@18:00 UTC will generate three bank files daily at 5:00, 13:00, and 18:00 UTC.
velocityDispachingActive
TRUE or FALSE
velocityDispatchingSetting
[A-Z a-z 0-9], [-_ ]32
{Maximum number of Tx};{Maximum volume};{within};{HOUR|DAY|WEEK|MONTH|YEAR} For example, 12;11;2;DAY
ticketSizeDispatchingActive
TRUE or FALSE
ticketSizeDispatchingSetting
[A-Z a-z 0-9], [-_; ]32
{Minimum ticket size};{Maximum ticket size} For example, 2;10
recurringDispatchingSetting
ALL: All shoppers TRUE: Recurring shoppers FALSE: First-time shoppers
shopperDispatchingSetting
ALL: All shoppers TRUE: Recurring shoppers FALSE: First-time shoppers
shopperDispatchingScope
PSP, DIVISION, MERCHANT, or CHANNEL
shopperDispatchingValidity
In days
paymentDispatchingSetting
ALL, CREDITS, DEBITS or ONLINE_TRANSFER
pendingTimeoutInMins
[0-9]
Define time in minutes when this payment request from Consumer should timeout.
pendingForAcquirerTimeoutInMins
[0-9]
Define time in minutes when the final payment status request from Acquirer should timeout.
uploadUser
–
uploadPassword
–
connectorSpecificParameter.&lt;parameter&gt;
[A-Z a-z 0-9], [-_ ]any
Acceptor data parameters set up in the request that is supported by the clearing institute.

Error response

200.*.*Used to tunnel errors. Check the error message.
POST/psps/{pspid}/ownedMerchantAccounts
POST/divisions/{divisionsid}/ownedMerchantAccounts
POST/merchants/{merchantid}/ownedMerchantAccounts
POST/channels/{channelid}/ownedMerchantAccounts

Request sample

curl -X POST \
  'https://eu-test.oppwa.com/bip/webapi/v1/psps/{pspId}/ownedMerchantAccounts' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>' \
  -H 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \
  --data-urlencode 'name=Test_merchant_account' \
  --data-urlencode 'state=TEST' \
  --data-urlencode 'clearingInstituteId=ff8081816030b48a016030b49a6c0014' \
  --data-urlencode 'iban=TT1234TTT00000000' \
  --data-urlencode 'username=testusername' \
  --data-urlencode 'password=testpassword' \
  --data-urlencode 'merchantCategory=RETAIL' \
  --data-urlencode 'transactionCategory=ECOMMERCE' \
  --data-urlencode 'avsCheckActive=TRUE' \
  --data-urlencode 'avsRejectionPolicy=A' \
  --data-urlencode 'avsReviewPolicy=A' \
  --data-urlencode 'debitAdviceProcedure=DD' \
  --data-urlencode 'recurringCode=NONE' \
  --data-urlencode 'supports3DSecure=TRUE' \
  --data-urlencode 'merchant3DName=test' \
  --data-urlencode 'merchant3DUrl=https://test.com/3d' \
  --data-urlencode 'merchantIsoCountryCode=630' \
  --data-urlencode 'bankfileGenerationPattern=DAILY@5:00 UTC' \
  --data-urlencode 'velocityDispachingActive=TRUE' \
  --data-urlencode 'velocityDispatchingSetting=12;11;2;DAY' \
  --data-urlencode 'ticketSizeDispatchingActive=TRUE' \
  --data-urlencode 'ticketSizeDispatchingSetting=2;10' \
  --data-urlencode 'recurringDispatchingSetting=ALL' \
  --data-urlencode 'shopperDispatchingSetting=ALL' \
  --data-urlencode 'shopperDispatchingScope=PSP' \
  --data-urlencode 'shopperDispatchingValidity=10' \
  --data-urlencode 'paymentDispatchingSetting=CREDITS' \
  --data-urlencode 'uploadUser=uploadUsername' \
  --data-urlencode 'uploadPassword=uploadPass' \
  --data-urlencode 'connectorSpecificParameter.AD_SUB_MERCHANT_CITY=subMerchantCity' \
  --data-urlencode 'connectorSpecificParameter.AD_SUB_MERCHANT_EMAIL=subMerchantEmail' \
  --data-urlencode 'connectorSpecificParameter.AD_SUB_MERCHANT_STATE=subMerchantState'

Response samples

{
  "id": "ab12cd34ef56ab12cd34ef56ab12cd86",
  "merchantAccount": {
    "avsCheckActive": "false",
    "avsRejectionPolicy": "N",
    "avsReviewPolicy": "",
    "bankfileGenerationPattern": "",
    "clearingInstitute": "Klarna Test",
    "connectorSpecificParameter": {
      "AD_SUB_MERCHANT_STATE": "subMerchantState",
      "AD_SUB_MERCHANT_CITY": "subMerchantCity",
      "AD_SUB_MERCHANT_EMAIL": "subMerchantEmail"
    },
    "cvvInstruction": "CHECK",
    "cvvRejectionPolicy": "N",
    "debitAdviceProcedure": "",
    "id": "ab12cd34ef56ab12cd34ef56ab12cd86",
    "merchantCategory": "",
    "name": "moapi_Klarna_MA_1",
    "password": "7JyRENbxSreJEYv",
    "paymentDispatchingSetting": "ALL",
    "recurringCode": "NONE",
    "recurringDispatchingSetting": "ALL",
    "shopperDispatchingScope": "CHANNEL",
    "shopperDispatchingSetting": "ALL",
    "shopperDispatchingValidity": "90",
    "state": "LIVE",
    "ticketSizeDispatchingSetting": "null;null",
    "transactionCategory": "ANY",
    "username": "129",
    "velocityDispachtingActive": "false"
  }
}

Get Merchant Account

The call gets the information about an existing merchant account.

Endpoints

GET/merchantAccounts/{merchantAccountId}
Get a merchant account using merchantAccountID.

URL parameters

merchantAccountIdrequired
[a-f 0-9]32
The ID of the merchant account.

Data parameters

No parameters are required.

Success response

200: OKThe request was successful.
name
[A-Z a-z 0-9], [-_ ]256
The name of the merchant account.
state
Possible values are "LIVE", "CLOSED", "TEST" or "DISABLED"
clearingInstitute
[A-Z a-z 0-9], [-_ ]32
The ID or name of the clearing institute, as listed in the GET response, querying the clearing institute list. See 03 Clearing Institute operations for the list of operations and the merchant account configuration per clearing institute.
iban
[A-Z a-z 0-9], [-_ ]32
–
key
[A-Z a-z 0-9], [-_ ]500
–
terminalId
anyany
–
password
[A-Z a-z 0-9], [-_ ]128
–
username
[A-Z a-z 0-9], [-_ ]128
–
merchantCategory
Possible values are: RETAIL, SERVICES, AIRLINE, HOTEL, TRAVEL, GAMING, GAMBLING, DIGITAL_CONTENT, AUCTION, ADULT, UTILITIES, E_TICKETING or ONLINE_FINANCIAL
transactionCategory
Possible values are: ANY, MOTO, ECOMMERCE, EWALLET
cvvInstruction
–
cvvRejectionPolicy
–
avsCheckActive
TRUE or FALSE
avsRejectionPolicy
Possible values are: A, Z, N, U
avsReviewPolicy
Possible values are: A, Z, N, U
debitAdviceProcedure
Possible values are: DA or DD
recurringCOde
Possible values are: NONE, RECURRING, INSTALLMENT
supports3DSecure
TRUE or FALSE
merchant3DName
anyany
–
merchant3DUrl
anyany
–
merchantIsoCountryCode
–
visaMerchantId
[A-Z]2
–
visaMerchantAcquirerBin
–
masterMerchantId
–
masterMerchantAcquirerBin
–
amexMerchantId
–
amexMerchantAcquirerBin
–
bcmcMerchantId
–
bcmcMerchantAcquirerBin
–
dinersMerchantId
–
dinersMerchantAcquirerBin
–
dinersMerchantPwd
–
jcbMerchantId
–
jcbMerchantAcquirerBin
–
bankfileGenerationPattern
[A-Z a-z 0-9], [-_ ]20
Bank files can be generated weekly or daily.
  • Weekly bank files are generated one time during the selected day of the week.
    For example, MONDAY@13:00 UTC will generate one bank file on Monday at 13:00 UTC.

  • Daily bank files can be generated as many as three times a day.
    For example:
    DAILY@5:00 UTC will generate one bank file daily at 5:00 UTC.
    DAILY@5:00 UTC+DAILY@13:00 UTC will generate two bank files daily at 5:00 and 13:00 UTC.
    DAILY@5:00 UTC+DAILY@13 UTC+DAILY@18:00 UTC will generate three bank files daily at 5:00, 13:00, and 18:00 UTC.
velocityDispachingActive
TRUE or FALSE
velocityDispatchingSetting
[A-Z a-z 0-9], [-_ ]32
{Maximum number of Tx};{Maximum volume};{within};{HOUR|DAY|WEEK|MONTH|YEAR} For example, 12;11;2;DAY
ticketSizeDispatchingActive
TRUE or FALSE
ticketSizeDispatchingSetting
[A-Z a-z 0-9], [-_; ]32
{Minimum ticket size};{Maximum ticket size} For example, 2;10
recurringDispatchingSetting
ALL: All shoppers TRUE: Recurring shoppers FALSE: First-time shoppers
shopperDispatchingSetting
ALL: All shoppers TRUE: Recurring shoppers FALSE: First-time shoppers
shopperDispatchingScope
PSP, DIVISION, MERCHANT, or CHANNEL
shopperDispatchingValidity
In days
paymentDispatchingSetting
ALL, CREDITS, DEBITS or ONLINE_TRANSFER
pendingTimeoutInMins
[0-9]
Define time in minutes when this payment request from Consumer should timeout.
pendingForAcquirerTimeoutInMins
[0-9]
Define time in minutes when the final payment status request from Acquirer should timeout.
uploadUser
–
uploadPassword
–
connectorSpecificParameter.&lt;parameter&gt;
[A-Z a-z 0-9], [-_ ]any
Acceptor data parameters supported by the clearing institute.
visaAcquirerMerchantId
Visa acquirer merchant id
masterAcquirerMerchantId
Mastercard acquirer merchant id
amexAcquirerMerchantId
Amex acquirer merchant id

Error response

200.*.*Used to tunnel errors. Check the error message.
GET/merchantAccounts/{merchantAccountId}

Request sample

curl -X GET \
  'https://eu-test.oppwa.com/bip/webapi/v1/merchantAccounts/{merchantAccountId}' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "id": "ab12cd34ef56ab12cd34ef56ab12cd86",
  "merchantAccount": {
    "avsCheckActive": "false",
    "avsRejectionPolicy": "N",
    "avsReviewPolicy": "",
    "bankfileGenerationPattern": "",
    "clearingInstitute": "Klarna Test",
    "connectorSpecificParameter": {
      "AD_SUB_MERCHANT_STATE": "subMerchantState",
      "AD_SUB_MERCHANT_CITY": "subMerchantCity",
      "AD_SUB_MERCHANT_EMAIL": "subMerchantEmail"
    },
    "cvvInstruction": "CHECK",
    "cvvRejectionPolicy": "N",
    "debitAdviceProcedure": "",
    "id": "ab12cd34ef56ab12cd34ef56ab12cd86",
    "merchantCategory": "",
    "name": "moapi_Klarna_MA_1",
    "password": "7JyRENbxSreJEYv",
    "paymentDispatchingSetting": "ALL",
    "recurringCode": "NONE",
    "recurringDispatchingSetting": "ALL",
    "shopperDispatchingScope": "CHANNEL",
    "shopperDispatchingSetting": "ALL",
    "shopperDispatchingValidity": "90",
    "state": "LIVE",
    "ticketSizeDispatchingSetting": "null;null",
    "transactionCategory": "ANY",
    "username": "129",
    "velocityDispachtingActive": "false"
  }
}

Edit Merchant Account

The call edits an existing merchant account.

Endpoints

POST/merchantAccounts/{merchantAccountId}
Edit a merchant account using merchantAccountId.

URL parameters

merchantAccountIdrequired
[a-f 0-9]32
The ID of the merchant account.

Data parameters

If the request is submitted with parameters set to empty spaces, for example, terminalIDs=<single space>, the previous value is deleted and the field is blank.
Parameters not included in the request are not changed. To avoid nullifying valid values, skip parameters that do not require an update.

name
[A-Z a-z 0-9], [-_ ]256
The name of the merchant account.
state
Possible values are "LIVE", "CLOSED", "TEST" or "DISABLED"
clearingInstituteIdclearingInstituteName
[a-f 0-9]32
The ID or name of the Clearing Institute, as listed in the GET response, querying the clearing institute list. See 03 Clearing Institute operations for the list of operations and the merchant account configuration per clearing institute.
iban
[A-Z a-z 0-9], [-_ ]32
–
key
[A-Z a-z 0-9], [-_ ]500
–
terminalId
anyany
–
password
[A-Z a-z 0-9], [-_ ]128
–
username
[A-Z a-z 0-9], [-_ ]128
–
merchantCategory
Possible values are: RETAIL, SERVICES, AIRLINE, HOTEL, TRAVEL, GAMING, GAMBLING, DIGITAL_CONTENT, AUCTION, ADULT, UTILITIES, E_TICKETING or ONLINE_FINANCIAL
transactionCategory
Possible values are: ANY, MOTO, ECOMMERCE, EWALLET
cvvInstruction
–
cvvRejectionPolicy
–
avsCheckActive
TRUE or FALSE
avsRejectionPolicy
Possible values are: A, Z, N, U
avsReviewPolicy
Possible values are: A, Z, N, U
debitAdviceProcedure
Possible values are: DA or DD
recurringCode
Possible values are: NONE, RECURRING, INSTALLMENT
supports3DSecure
TRUE or FALSE
merchant3DName
anyany
–
merchant3DUrl
anyany
–
merchantIsoCountryCode
–
visaMerchantId
[A-Z]2
–
visaMerchantAcquirerBin
–
masterMerchantId
–
masterMerchantAcquirerBin
–
amexMerchantId
–
amexMerchantAcquirerBin
–
bcmcMerchantId
–
bcmcMerchantAcquirerBin
–
dinersMerchantId
–
dinersMerchantAcquirerBin
–
dinersMerchantPwd
–
jcbMerchantId
–
jcbMerchantAcquirerBin
–
bankfileGenerationPattern
[A-Z a-z 0-9], [-_:@ ]20
Bank files can be generated weekly or daily.
  • Weekly bank files are generated only one time during the selected day of the week.
    For example, MONDAY@13:00 UTC will generate one bank file on Monday at 13:00 UTC.

  • Daily bank files can be generated up to three times a day.
    For example,
    DAILY@5:00 UTC will generate one bank file daily at 5:00 UTC.
    DAILY@5:00 UTC+DAILY@13:00 UTC will generate two bank files daily at 5:00 and 13:00 UTC.
    DAILY@5:00 UTC+DAILY@13 UTC+DAILY@18:00 UTC will generate three bank files daily at 5:00, 13:00, and 18:00 UTC.
velocityDispachingActive
TRUE or FALSE
velocityDispatchingSetting
[A-Z a-z 0-9], [-_; ]32
{Maximum number of Tx};{Maximum volume};{within};{HOUR|DAY|WEEK|MONTH|YEAR} For example, 12;11;2;DAY
ticketSizeDispatchingActive
TRUE or FALSE
ticketSizeDispatchingSetting
[A-Z a-z 0-9], [-_; ]32
{Minimum ticket size};{Maximum ticket size} For example, 2;10
recurringDispatchingSetting
ALL: All shoppers TRUE: Recurring shoppers FALSE: First-time shoppers
shopperDispatchingSetting
ALL: All shoppers TRUE: Recurring shoppers FALSE: First-time shoppers
shopperDispatchingScope
PSP, DIVISION, MERCHANT, or CHANNEL
shopperDispatchingValidity
in days
paymentDispatchingSetting
ALL, CREDITS, DEBITS or ONLINE_TRANSFER
pendingTimeoutInMins
[0-9]
Define time in minutes when this payment request from Consumer should timeout.
pendingForAcquirerTimeoutInMins
[0-9]
Define time in minutes when the final payment status request from Acquirer should timeout.
uploadUser
–
uploadPassword
–
connectorSpecificParameter.&lt;parameter&gt;
[A-Z a-z 0-9], [-_ ]any
Acceptor data parameters are specific to each connector/clearing institute. For possible values please consult the connector integration sheet.

Success response

200: OKThe request was successful.
name
[A-Z a-z 0-9], [-_ ]256
The name of the merchant account.
state
Possible values are "LIVE", "CLOSED", "TEST" or "DISABLED"
clearingInstitute
[A-Z a-z 0-9], [-_ ]32
The ID or name of the clearing institute, as listed in the GET response, querying the clearing institute list. See 03 Clearing Institute operations for the list of operations and the merchant account configuration per clearing institute.
iban
[A-Z a-z 0-9], [-_ ]32
–
key
[A-Z a-z 0-9], [-_ ]500
–
terminalId
anyany
–
password
[A-Z a-z 0-9], [-_ ]128
–
username
[A-Z a-z 0-9], [-_ ]128
–
merchantCategory
Possible values are: RETAIL, SERVICES, AIRLINE, HOTEL, TRAVEL, GAMING, GAMBLING, DIGITAL_CONTENT, AUCTION, ADULT, UTILITIES, E_TICKETING or ONLINE_FINANCIAL
transactionCategory
Possible values are: ANY, MOTO, ECOMMERCE, EWALLET
cvvInstruction
–
cvvRejectionPolicy
–
avsCheckActive
TRUE or FALSE
avsRejectionPolicy
Possible values are: A, Z, N, U
avsReviewPolicy
Possible values are: A, Z, N, U
debitAdviceProcedure
Possible values are: DA or DD
recurringCode
Possible values are: NONE, RECURRING, INSTALLMENT
supports3DSecure
TRUE or FALSE
merchant3DName
anyany
–
merchant3DUrl
anyany
–
merchantIsoCountryCode
–
visaMerchantId
[A-Z]2
–
visaMerchantAcquirerBin
–
masterMerchantId
–
masterMerchantAcquirerBin
–
amexMerchantId
–
amexMerchantAcquirerBin
–
bcmcMerchantId
–
bcmcMerchantAcquirerBin
–
dinersMerchantId
–
dinersMerchantAcquirerBin
–
dinersMerchantPwd
–
jcbMerchantId
–
jcbMerchantAcquirerBin
–
bankfileGenerationPattern
[A-Z a-z 0-9], [-_ ]20
Bank files can be generated weekly or daily.
  • Weekly bank files are generated one time during the selected day of the week.
    For example, MONDAY@13:00 UTC will generate one bank file on Monday at 13:00 UTC.

  • Daily bank files can be generated as many as three times a day.
    For example,
    DAILY@5:00 UTC will generate one bank file daily at 5:00 UTC.
    DAILY@5:00 UTC+DAILY@13:00 UTC will generate two bank files daily at 5:00 and 13:00 UTC.
    DAILY@5:00 UTC+DAILY@13 UTC+DAILY@18:00 UTC will generate three bank files daily at 5:00, 13:00, and 18:00 UTC.
velocityDispachingActive
TRUE or FALSE
velocityDispatchingSetting
[A-Z a-z 0-9], [-_ ]32
{Maximum number of Tx};{Maximum volume};{within};{HOUR|DAY|WEEK|MONTH|YEAR} For example, 12;11;2;DAY
ticketSizeDispatchingActive
TRUE or FALSE
ticketSizeDispatchingSetting
[A-Z a-z 0-9], [-_; ]32
{Minimum ticket size};{Maximum ticket size}
For example, 2;10
recurringDispatchingSetting
ALL: All shoppers TRUE: Recurring shoppers FALSE: First-time shoppers
shopperDispatchingSetting
ALL: All shoppers TRUE: Recurring shoppers FALSE: First-time shoppers
shopperDispatchingScope
PSP, DIVISION, MERCHANT, or CHANNEL
shopperDispatchingValidity
in days
paymentDispatchingSetting
ALL, CREDITS, DEBITS or ONLINE_TRANSFER
pendingTimeoutInMins
[0-9]
Define time in minutes when this payment request from Consumer should timeout.
pendingForAcquirerTimeoutInMins
[0-9]
Define time in minutes when the final payment status request from Acquirer should timeout.
uploadUser
–
uploadPassword
–
connectorSpecificParameter.&lt;parameter&gt;
[A-Z a-z 0-9], [-_ ]any
Acceptor data parameters set up in the request that is supported by the clearing institute.

Error response

200.*.*Used to tunnel errors. Check the error message.
POST/merchantAccounts/{merchantAccountId}

Request sample

curl -X POST \
  'https://eu-test.oppwa.com/bip/webapi/v1/merchantAccounts/{merchantAccountId}' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>' \
  -H 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \
  --data-urlencode 'name=Test_merchant_account' \
  --data-urlencode 'state=TEST' \
  --data-urlencode 'clearingInstituteId=ff8081816030b48a016030b49a6c0014' \
  --data-urlencode 'iban=TT1234TTT00000000' \
  --data-urlencode 'username=testusername' \
  --data-urlencode 'password=testpassword' \
  --data-urlencode 'merchantCategory=RETAIL' \
  --data-urlencode 'transactionCategory=ECOMMERCE' \
  --data-urlencode 'avsCheckActive=TRUE' \
  --data-urlencode 'avsRejectionPolicy=A' \
  --data-urlencode 'avsReviewPolicy=A' \
  --data-urlencode 'debitAdviceProcedure=DD' \
  --data-urlencode 'recurringCode=NONE' \
  --data-urlencode 'supports3DSecure=TRUE' \
  --data-urlencode 'merchant3DName=test' \
  --data-urlencode 'merchant3DUrl=https://test.com/3d' \
  --data-urlencode 'merchantIsoCountryCode=630' \
  --data-urlencode 'bankfileGenerationPattern=DAILY@5:00 UTC' \
  --data-urlencode 'velocityDispachingActive=TRUE' \
  --data-urlencode 'velocityDispatchingSetting=12;11;2;DAY' \
  --data-urlencode 'ticketSizeDispatchingActive=TRUE' \
  --data-urlencode 'ticketSizeDispatchingSetting=2;10' \
  --data-urlencode 'recurringDispatchingSetting=ALL' \
  --data-urlencode 'shopperDispatchingSetting=ALL' \
  --data-urlencode 'shopperDispatchingScope=PSP' \
  --data-urlencode 'shopperDispatchingValidity=10' \
  --data-urlencode 'paymentDispatchingSetting=CREDITS' \
  --data-urlencode 'uploadUser=uploadUsername' \
  --data-urlencode 'uploadPassword=uploadPass' \
  --data-urlencode 'connectorSpecificParameter.AD_SUB_MERCHANT_CITY=subMerchantCity' \
  --data-urlencode 'connectorSpecificParameter.AD_SUB_MERCHANT_EMAIL=subMerchantEmail' \
  --data-urlencode 'connectorSpecificParameter.AD_SUB_MERCHANT_STATE=subMerchantState'

Response samples

{
  "id": "ab12cd34ef56ab12cd34ef56ab12cd86",
  "merchantAccount": {
    "avsCheckActive": "false",
    "avsRejectionPolicy": "N",
    "avsReviewPolicy": "",
    "bankfileGenerationPattern": "",
    "clearingInstitute": "Klarna Test",
    "connectorSpecificParameter": {
      "AD_SUB_MERCHANT_STATE": "subMerchantState",
      "AD_SUB_MERCHANT_CITY": "subMerchantCity",
      "AD_SUB_MERCHANT_EMAIL": "subMerchantEmail"
    },
    "cvvInstruction": "CHECK",
    "cvvRejectionPolicy": "N",
    "debitAdviceProcedure": "",
    "id": "ab12cd34ef56ab12cd34ef56ab12cd86",
    "merchantCategory": "",
    "name": "moapi_Klarna_MA_0",
    "password": "7JyRENbxSreJEYv",
    "paymentDispatchingSetting": "ALL",
    "recurringCode": "NONE",
    "recurringDispatchingSetting": "ALL",
    "shopperDispatchingScope": "CHANNEL",
    "shopperDispatchingSetting": "ALL",
    "shopperDispatchingValidity": "90",
    "state": "LIVE",
    "ticketSizeDispatchingSetting": "null;null",
    "transactionCategory": "ANY",
    "username": "129",
    "velocityDispachtingActive": "false"
  }
}

Delete Merchant Account

The call sets the state of an existing merchant account to ‘DISABLED’.
It is not possible to delete a merchant account.

Endpoints

DELETE/merchantAccounts/{merchantAccountId}
Delete a merchant account using merchantAccountId.

URL parameters

merchantAccountIdrequired
[a-f 0-9]32
The ID of the merchant account.

Data parameters

No parameters are required.

Success response

200: OKThe request was successful.

No response body.

Error response

200.*.*Used to tunnel errors. Check the error message.
DELETE/merchantAccounts/{merchantAccountId}

Request sample

curl -X DELETE \
  'https://eu-test.oppwa.com/bip/webapi/v1/merchantAccounts/{merchantAccountId}' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{}

Attach Merchant Account

The call allows to attachment of a merchant account to the desired entity.
The merchant account can be created at one level and then attached to another entity at another level.

Endpoints

POST/psps/{pspid}/attachedMerchantAccounts
Option 1. Attach a merchant accountusing pspID.
POST/divisions/{divisionid}/attachedMerchantAccounts
Option 2. Attach a merchant accountusing divisionID.
POST/merchants/{merchantid}/attachedMerchantAccounts
Option 3. Attach a merchant accountusing merchantID.
POST/channels/{channelId}/attachedMerchantAccounts
Option 4. List the attached Merchant Accounts using channelID.

URL parameters

pspIdrequired for option 1
[a-f 0-9]32
The ID of the PSP.
divisionIdrequired for option 2
[a-f 0-9]32
The ID of the division.
merchantIdrequired for option 3
[a-f 0-9]32
The ID of the merchant.
channelIdrequired for option 4
[a-f 0-9]32
The ID of the channel.

Data parameters

merchantAccountId
[A-Z a-z 0-9], [-_ ]32
The ID of the entity, at which level the merchant accountwill be attached.
fallbackMerchantAccountIdOptional
[A-Z a-z 0-9], [-_ ]32
The ID of the fallback merchant account.
processTransactionsWithoutBinIdentificationOptional
true or false
Denotes transactions on the attached merchant account when BIN couldn't be identified (default: false).
currency
[A-Z]
The supported currency, named using the 3-character currency codes. Only one currency as input, no list of currencies is possible. For example, "EUR", "USD"
binCountryLimit
[A-Z], [;]
The list of country codes, separated by semicolons, written using the 2-char codes For example, “DE;NL;CA” or “DE” or “”
binRangeLimit
[0-9]
The list of ranges, separated by semicolons. Each range is two 6-digit or two 8-digit numbers, separated by a colon.
For example, “420000:440000;510000:520000” or “000000:999999” or “” or “42000000:44000000;51000000:52000000” or “00000000:99999999”
subTypes
Can be a comma-separated list; For example, "VISA, MASTER"
clearingInstituteIdclearingInstituteName
[a-f 0-9]32
The ID or name of the clearing institute, as listed in the GET response, querying the clearing institute list. See 03 Clearing Institute operations for the list of operations and the merchant account configuration per clearing institute.
customDescriptor1 customDescriptor2 customDescriptor3Optional
[A-Z a-z 0-9], [-_ ]
All three custom descriptor fields can contain a description of choice. The custom descriptor and selection descriptor fields provided are concatenated as follows: “{customDescriptor1}{selectionDescriptor1}{customDescriptor2}{selectionDescriptor2}{customDescriptor3}{selectionDescriptor3}”
selectionDescriptor1 selectionDescriptor2 selectionDescriptor3Optional
[A-Z a-z 0-9], [-_ ]
Can be one of these, case-sensitive, options “”, “CHANNEL_NAME”, “MERCHANT_NAME”, “USAGE”, “TRANSACTION_ID”, “INVOICE_ID”, “SHORT_ID”, “INV”, “INVC”, “Re”, “Rech”, “Renr”, “RNr”, “R.-Nr.” Can be one of these, case-sensitive, options “”, “CHANNEL_NAME”, “MERCHANT_NAME”, “USAGE”, “TRANSACTION_ID”, “INVOICE_ID”, “SHORT_ID” Can be the same options as selectionDescriptor2.

Success response

200: OKThe request was successful.
attachedMerchantAccount
Object containing all fields necessary to send a transaction with the same names as used in the transaction XML.
id
[A-Z a-z 0-9], [-_ ]32
The ID of the entity, at which level the merchant account will be attached.
currency
[A-Z]
The supported currency, named using the 3-character currency codes. For example, "EUR", "USD"
binCountryLimit
[A-Z]
The list of country codes, separated by semicolons, written using the 2-character codes For example, “DE;NL;CA” or “DE” or “”
binRangeLimit
[0-9]
The list of ranges, separated by semicolons. Each range is two 6-digit or two 8-digit numbers, separated by a colon.
For example, “420000:440000;510000:520000” or “000000:999999” or “” or “42000000:44000000;51000000:52000000” or “00000000:99999999”
processTransactionsWithoutBinIdentification
true or false
Returns true or false, if attached merchant account has enabled/disabled process transactions without BIN identification.
subTypes
Can be a comma-separated list; for example, "VISA, MASTER"
clearingInstitute
[A-Z a-z 0-9], [-_ ]32
The ID or name of the clearing institute, as listed in the GET response, querying the clearing institute list. See 03 Clearing Institute operations for the list of operations and the merchant account configuration per clearing institute.
descriptor
[A-Z a-z 0-9], [-_ ]255
The custom descriptor and selection descriptor fields, concatenated as follows: “{customDescriptor1}{selectionDescriptor1}{customDescriptor2}{selectionDescriptor2}{customDescriptor3}{selectionDescriptor3}”

Error response

200.*.*Used to tunnel errors. Check the error message.
Note. For the fallbackMerchantAccountId to be used as the fallback, one of the following RiRos must be enabled:Smart retry standalone payments with the fallback acquirerSmart retry payments referencing a registration with the fallback acquirer
POST/psps/{pspid}/attachedMerchantAccounts
POST/divisions/{divisionid}/attachedMerchantAccounts
POST/merchants/{merchantid}/attachedMerchantAccounts
POST/channels/{channelId}/attachedMerchantAccounts

Request sample

curl -X POST \
  'https://eu-test.oppwa.com/bip/webapi/v1/psps/{pspId}/attachedMerchantAccounts' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>' \
  -H 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \
  --data-urlencode 'merchantAccountId=ff8081816953558101695716b6c70014' \
  --data-urlencode 'fallbackMerchantAccountId=ff8081817ad3d41d017ad3d45370010a' \
  --data-urlencode 'currency=EUR' \
  --data-urlencode 'binCountryLimit=DE;RO;US' \
  --data-urlencode 'binRangeLimit=000000:999999' \
  --data-urlencode 'processTransactionsWithoutBinIdentification=true' \
  --data-urlencode 'subTypes=VISA' \
  --data-urlencode 'clearingInstituteId=ff8081816030b48a016030b49a6c0014' \
  --data-urlencode 'customDescriptor1=AAA' \
  --data-urlencode 'customDescriptor2=BBB' \
  --data-urlencode 'customDescriptor3=CCC' \
  --data-urlencode 'selectionDescriptor1=CHANNEL_NAME' \
  --data-urlencode 'selectionDescriptor2=INVOICE_ID' \
  --data-urlencode 'selectionDescriptor3=TRANSACTION_ID'

Response samples

{
  "attachedMerchantAccount": {
    "binCountryLimit": "",
    "binRangeLimit": "",
    "clearingInstitute": "Klarna Test",
    "currency": "EUR",
    "descriptor": "",
    "id": "ab12cd34ef56ab12cd34ef56ab12cd89",
    "merchantAccountId": "ab12cd34ef56ab12cd34ef56ab12cd86",
    "processTransactionsWithoutBinIdentification": false,
    "subTypes": "VISA"
  },
  "id": "ab12cd34ef56ab12cd34ef56ab12cd89"
}

Edit Attached Merchant Account

The call edits an attached merchant account.

Endpoints

POST/attachedMerchantAccounts/{attachedMerchantAccountId}
Edit an attached merchant account using attachedMerchantId.

URL parameters

attachedMerchantAccountIdrequired
[a-f 0-9]32
The ID of the attached merchant account.

Data parameters

merchantAccountId
[a-f 0-9]32
The ID of the merchant account, for which the changes are submitted.
fallbackMerchantAccountId
[a-f 0-9]32
The ID of the merchant account to be set as a fallback.
processTransactionsWithoutBinIdentificationOptional
true or false
Denotes transactions on the attached merchant account when BIN couldn't be identified (default: false).
currency
[A-Z]
The supported currency, named using the 3-character currency codes. Only one currency as input, no list of currencies is possible. For example, "EUR", "USD"
binCountryLimit
[A-Z], [;]
The list of country codes, separated by semicolons, written using the 2-char codes. For example, “DE;NL;CA” or “DE” or “”
binRangeLimit
[0-9]
The list of ranges, separated by semicolons. Each range is two 6-digit or two 8-digit numbers, separated by a colon. For example, “420000:440000;510000:520000” or “000000:999999” or “” or “42000000:44000000;51000000:52000000” or “00000000:99999999”
subTypes
Can be a comma-separated list; For example, "VISA, MASTER"
clearingInstituteIdclearingInstituteName
[a-f 0-9]32
The ID or name of the Clearing Institute, as listed in the GET response, querying the clearing institute list. See 03 Clearing Institute operations for the list of operations and the merchant account configuration per clearing institute.
customDescriptor1 customDescriptor2 customDescriptor3Optional
[A-Z a-z 0-9], [-_ ]
All three custom descriptor fields can contain a description of choice. The custom descriptor and selection descriptor fields provided are concatenated as follows: “{customDescriptor1}{selectionDescriptor1}{customDescriptor2}{selectionDescriptor2}{customDescriptor3}{selectionDescriptor3}”
selectionDescriptor1 selectionDescriptor2 selectionDescriptor3Optional
[A-Z a-z 0-9], [-_ ]
Can be one of these, case-sensitive, options “”, “CHANNEL_NAME”, “MERCHANT_NAME”, “USAGE”, “TRANSACTION_ID”, “INVOICE_ID”, “SHORT_ID”, “INV”, “INVC”, “Re”, “Rech”, “Renr”, “RNr”, “R.-Nr.” Can be one of these, case-sensitive, options “”, “CHANNEL_NAME”, “MERCHANT_NAME”, “USAGE”, “TRANSACTION_ID”, “INVOICE_ID”, “SHORT_ID” Can be the same options as selectionDescriptor2.

Success response

200: OKThe request was successful.
attachedMerchantAccount
Object containing all fields necessary to send a transaction with the same names as used in the transaction XML.
id
[A-Z a-z 0-9], [-_ ]32
The ID of the entity, at which level the merchant account will be attached.
currency
[A-Z]
The supported currency, named using the 3-char currency codes. For example, "EUR", "USD"
binCountryLimit
[A-Z], [;]
The list of country codes, separated by semicolons, written using the 2-char codes. For example, “DE;NL;CA” or “DE” or “”
binRangeLimit
[0-9], [:;]
The list of ranges, separated by semicolons. Each range is two 6-digit or two 8-digit numbers, separated by a colon. For example, “420000:440000;510000:520000” or “000000:999999” or “” or “42000000:44000000;51000000:52000000” or “00000000:99999999”
processTransactionsWithoutBinIdentification
true or false
Returns true or false, if attached merchant account has enabled/disabled process transactions without BIN identification.
subTypes
Can be a comma-separated list; For example, "VISA, MASTER"
clearingInstitute
[A-Z a-z 0-9], [-_ ]32
The ID or name of the clearing institute, as listed in the GET response, querying the clearing institute list. See 03 Clearing Institute operations for the list of operations and the merchant account configuration per clearing institute.
descriptor
[A-Z a-z 0-9], [-_ ]255
The custom descriptor and selection descriptor fields, concatenated as follows: “{customDescriptor1}{selectionDescriptor1}{customDescriptor2}{selectionDescriptor2}{customDescriptor3}{selectionDescriptor3}”

Error response

200Used to tunnel errors. Check the error message.
Note. For the fallbackMerchantAccountId to be used as a fallback, one of the following RiRos must be enabled:Smart retry standalone payments with fallback acquirerSmart retry payments referencing a registration with fallback acquirer
POST/attachedMerchantAccounts/{attachedMerchantAccountId}

Request sample

curl -X POST \
  'https://eu-test.oppwa.com/bip/webapi/v1/attachedMerchantAccounts/{attachedMerchantAccountId}' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>' \
  -H 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \
  --data-urlencode 'merchantAccountId=ff8081816953558101695716b6c70014' \
  --data-urlencode 'fallbackMerchantAccountId=ff8081817ad3d41d017ad3d45370010a' \
  --data-urlencode 'currency=EUR' \
  --data-urlencode 'binCountryLimit=DE;RO;US' \
  --data-urlencode 'binRangeLimit=000000:999999' \
  --data-urlencode 'processTransactionsWithoutBinIdentification=true' \
  --data-urlencode 'subTypes=VISA' \
  --data-urlencode 'clearingInstituteId=ff8081816030b48a016030b49a6c0014' \
  --data-urlencode 'customDescriptor1=AAA' \
  --data-urlencode 'customDescriptor2=BBB' \
  --data-urlencode 'customDescriptor3=CCC' \
  --data-urlencode 'selectionDescriptor1=CHANNEL_NAME' \
  --data-urlencode 'selectionDescriptor2=INVOICE_ID' \
  --data-urlencode 'selectionDescriptor3=TRANSACTION_ID'

Response samples

{
  "id": "1200818141111c3klq1f8410103f4064",
  "attachedMerchantAccount": {
    "id": "1200818141111c3klq1f8410103f4064",
    "processTransactionsWithoutBinIdentification": false,
    "currency": "EUR",
    "binCountryLimit": "DE;NL",
    "binRangeLimit": "420000:440000",
    "subTypes": "VISA",
    "clearingInstitute": "MyCI",
    "descriptor": ""
  }
}

Detach Merchant Account

The call detaches an attached merchant account.

Endpoints

DELETE/attachedMerchantAccounts/{attachedMerchantAccountId}
Delete an attached merchant account using attachedMerchantId.

URL parameters

attachedMerchantAccountIdrequired
[a-f 0-9]32
The ID of the attached merchant account. Use the value in the ID field from the response received by running the call 08 Get Attached Merchant Account list.

Data parameters

No parameters are required.

Success response

200: OKThe request was successful.

No response body.

Error response

200: OKUsed to tunnel errors. Check the error message.
DELETE/attachedMerchantAccounts/{attachedMerchantAccountId}

Request sample

curl -X DELETE \
  'https://eu-test.oppwa.com/bip/webapi/v1/attachedMerchantAccounts/{attachedMerchantAccountId}' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{}

Get Attached Merchant Account list

The call lists the information about merchant accounts that are attached to a specific entity. Do not confuse with 09 Get Owned Merchant Account list.
The call Get Attached Merchant Account list is getting the merchant accounts that are attached to an entity, but might have been created under a different entity.

Note. The call works when executed at PSP, Merchant, and Channel levels. At the moment the call does not work at Division level.

Endpoints

GET/psps/{pspid}/attachedMerchantAccounts
Option 1. List the attached merchant accounts using pspID.
GET/divisions/{divisionid}/attachedMerchantAccounts
Option 2. List the attached merchant accountsusing divisionID.
GET/merchants/{merchantid}/attachedMerchantAccounts
Option 3. List the attached merchant accountsusing merchantID.
GET/channels/{channelId}/attachedMerchantAccounts
Option 4. List the attached merchant accounts using channelID.

URL parameters

pspIdrequired for option 1
[a-f 0-9]32
The ID of the PSP.
divisionIdrequired for option 2
[a-f 0-9]32
The ID of the division.
merchantIdrequired for option 3
[a-f 0-9]32
The ID of the merchant.
channelIdrequired for option 4
[a-f 0-9]32
The ID of the channel.

Data parameters

No parameters are required

Success response

200: OKThe request was successful.
attachedMerchantAccount
Object containing all fields necessary to send a transaction with the same names as used in the transaction XML.
fallbackMerchantAccountId
The ID of the owned merchant account that will act as a fallback. If fallback is not set then this field will not appear in the response.
id
[A-Z a-z 0-9], [-_ ]32
The ID of the entity, at which level the merchant account will be attached.
currency
[A-Z]
The supported currency, named using the 3-character currency codes. For example, "EUR", "USD"
binCountryLimit
[A-Z]
The list of country codes, separated by semicolons, written using the 2-char codes. For example, “DE;NL;CA” or “DE” or “”
binRangeLimit
[0-9]
The list of ranges, separated by semicolons. Each range is two 6-digit numbers, separated by a colon. For example, “420000:440000;510000:520000” or “000000:999999” or “”
processTransactionsWithoutBinIdentification
true or false
Returns true or false, if attached merchant account has enabled/disabled process transactions without BIN identification.
subTypes
Can be a comma-separated list; for example,"VISA, MASTER"
clearingInstitute
[A-Z a-z 0-9], [-_ ]32
The ID or name of the clearing institute, as listed in the GET response, querying the clearing institute list. See 03 Clearing Institute operations for the list of operations and the merchant account configuration per clearing institute.
descriptor
[A-Z a-z 0-9], [-_ ]255
The custom descriptor and selection descriptor fields, concatenated as follows: “{customDescriptor1}{selectionDescriptor1}{customDescriptor2}{selectionDescriptor2}{customDescriptor3}{selectionDescriptor3}”

Error response

200.*.*Used to tunnel errors. Check the error message.
GET/psps/{pspid}/attachedMerchantAccounts
GET/divisions/{divisionid}/attachedMerchantAccounts
GET/merchants/{merchantid}/attachedMerchantAccounts
GET/channels/{channelId}/attachedMerchantAccounts

Request sample

curl -X GET \
  'https://eu-test.oppwa.com/bip/webapi/v1/psps/{pspId}/attachedMerchantAccounts' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "attachedMerchantAccounts": [
    {
      "binCountryLimit": "",
      "binRangeLimit": "",
      "clearingInstitute": "Klarna Test",
      "currency": "EUR",
      "descriptor": "",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd89",
      "merchantAccountId": "ab12cd34ef56ab12cd34ef56ab12cd86",
      "processTransactionsWithoutBinIdentification": false,
      "subTypes": "VISA"
    },
    {
      "binCountryLimit": "",
      "binRangeLimit": "",
      "clearingInstitute": "Klarna Test",
      "currency": "EUR",
      "descriptor": "",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd91",
      "merchantAccountId": "ab12cd34ef56ab12cd34ef56ab12cd92",
      "processTransactionsWithoutBinIdentification": false,
      "subTypes": "VISA"
    },
    {
      "binCountryLimit": "",
      "binRangeLimit": "",
      "clearingInstitute": "Klarna Test",
      "currency": "EUR",
      "descriptor": "",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd93",
      "merchantAccountId": "ab12cd34ef56ab12cd34ef56ab12cd86",
      "processTransactionsWithoutBinIdentification": false,
      "subTypes": "VISA"
    },
    {
      "binCountryLimit": "",
      "binRangeLimit": "",
      "clearingInstitute": "Klarna Test",
      "currency": "EUR",
      "descriptor": "",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd94",
      "merchantAccountId": "ab12cd34ef56ab12cd34ef56ab12cd90",
      "processTransactionsWithoutBinIdentification": false,
      "fallbackMerchantAccountId": "ab12cd34ef56ab12cd34ef56ab12cd86",
      "subTypes": "VISA"
    }
  ]
}

Get Owned Merchant Account list

The call lists the information about all merchant accounts that were created or attached at the level of a specific entity. Do not confuse with the Get Attached Merchant Account list.
The call Get Owned Merchant Account list is getting the merchant accounts that were created at the level of a specific entity but might have been attached to a different entity, and the merchant accounts that were attached to this specific entity.

Endpoints

GET/psps/{pspid}/ownedMerchantAccounts
Option 1. List the attached merchant accounts using pspID.
GET/divisions/{divisionid}/ownedMerchantAccounts
Option 2. List the attached merchant accountsusing divisionID.
GET/merchants/{merchantid}/ownedMerchantAccounts
Option 3. List the attached merchant accountsusing merchantID.
GET/channels/{channelId}/ownedMerchantAccounts
Option 4. List the attached merchant accounts using channelID.

URL parameters

pspIdrequired for option 1
[a-f 0-9]32
The ID of the PSP.
divisionIdrequired for option 2
[a-f 0-9]32
The ID of the division.
merchantIdrequired for option 3
[a-f 0-9]32
The ID of the merchant.
channelIdrequired for option 4
[a-f 0-9]32
The ID of the channel.

Data parameters

No parameters are required

Success response

200: OKThe request was successful.
id
[a-f 0-9]32
The ID of the entity, at which level the merchant account will be created.
name
[A-Z a-z 0-9], [-_ ]256
The name of the merchant account.
clearingInstitute
[A-Z a-z 0-9], [-_ ]32
The ID or name of the clearing institute, as listed in the GET response, querying the clearing institute list.
See 03 Clearing Institute operations for the list of operations and the merchant account configuration per clearing institute.
supports3DSecure
TRUE or FALSE

Error response

200.*.*Used to tunnel errors. Check the error message.
GET/psps/{pspid}/ownedMerchantAccounts
GET/divisions/{divisionid}/ownedMerchantAccounts
GET/merchants/{merchantid}/ownedMerchantAccounts
GET/channels/{channelId}/ownedMerchantAccounts

Request sample

curl -X GET \
  'https://eu-test.oppwa.com/bip/webapi/v1/psps/{pspId}/ownedMerchantAccounts' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "merchantAccounts": [
    {
      "clearingInstitute": "Klarna Test",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd90",
      "name": "moapi_Klarna_MA_2"
    },
    {
      "clearingInstitute": "Klarna Test",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd92",
      "name": "moapi_Klarna_MA_3"
    },
    {
      "clearingInstitute": "Klarna Test",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd96",
      "name": "moapi_Klarna_MA_4"
    },
    {
      "clearingInstitute": "Klarna Test",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd86",
      "name": "moapi_Klarna_MA_0"
    }
  ]
}

3D Secure setup

The 3D Secure setup requires executing two calls in sequence.

Note. This functionality is not fully implemented.

Endpoints

POST/merchantAccounts/{merchantAccountId}
1. Add the specific 3D Secure configuration to the selected Merchant Account ID:
POST/merchants/{merchantid}/setting
+ 2. Change the risk setting configuration parameter to a new value:

URL parameters

merchantAccountIdrequired
[a-f 0-9]32
The ID of the merchant account.

Data parameters

/merchantAccounts/{merchantAccountId}
–
supports3DSecurerequired
true/falseboolean
–
merchant3DNamerequired
–
merchant3DUrlrequired
–
merchantIsoCountryCoderequired
–
merchant3DIdrequired
–
merchant3DCategoryrequired
–
Visa configuration
–
visaAcquirerMerchantId
–
visaMerchantAcquirerBin_v2required
Required for 3D Secure v2.x
visaRequestorId_v2required
Required for 3D Secure v2.x
visaRequestorNamerequired
Required for 3D Secure v2.x
MasterCard configuration
–
masterAcquirerMerchantId
–
masterMerchantAcquirerBin_v2required
Required for 3D Secure v2.x
masterRequestorId_v2required
Required for 3D Secure v2.x
masterRequestorNamerequired
Required for 3D Secure v2.x
American Express configuration
–
amexAcquirerMerchantId
–
amexMerchantAcquirerBin_v2required
Required for 3D Secure v2.x
amexRequestorId_v2required
Required for 3D Secure v2.x
amexRequestorNamerequired
Required for 3D Secure v2.x
Diners configuration
–
dinersMerchantIdrequired
Required for 3D Secure v2.x
dinersMerchantAcquirerBin_v2required
Required for 3D Secure v2.x
dinersRequestorId_v2required
Required for 3D Secure v2.x
dinersRequestorNamerequired
Required for 3D Secure v2.x
BCMC configuration
–
bcmcMerchantAcquirerBin_v2required
Required for 3D Secure v2.x
bcmcRequestorId_v2required
Required for 3D Secure v2.x
bcmcRequestorNamerequired
Required for 3D Secure v2.x
JCB configuration
–
jcbMerchantAcquirerBin_v2
Required for 3D Secure v2.x
jcbRequestorId_v2
Required for 3D Secure v2.x
jcbRequestorName
Required for 3D Secure v2.x
CashlinkMalta configuration
–
cashlinkMaltaMerchantAcquirerBin_v2required
Required for 3D Secure v2.x
cashlinkMaltaRequestorId_v2required
Required for 3D Secure v2.x
cashlinkMaltaRequestorNamerequired
Required for 3D Secure v2.x
/merchants/*/setting
–
keyrequired
The value is */type:entity/module:ctpe/processing:risk/risk:threeDSecure/config:threeDType
valuerequired
Possible values are:
  • None
  • No 3DSecure
  • 3DSecure
  • 3DSecurePassThrough

Success response

200: OKThe request was successful.
merchantAccountId
[a-f 0-9]32
The ID of the merchant account.
to be added
–

Error response

200Used to tunnel errors. Check the error message.
POST/merchantAccounts/{merchantAccountId}
POST/merchants/{merchantid}/setting

Request sample

curl -X POST \
  'https://eu-test.oppwa.com/bip/webapi/v1/merchantAccounts/{merchantAccountId}' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>' \
  -H 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \
  --data-urlencode 'supports3DSecure=TRUE' \
  --data-urlencode 'merchant3DName=Merchant 3D name' \
  --data-urlencode 'merchant3DUrl=https://test.com/3d' \
  --data-urlencode 'merchantIsoCountryCode=630' \
  --data-urlencode 'visaMerchantId=12345' \
  --data-urlencode 'visaMerchantAcquirerBin=4200' \
  --data-urlencode 'masterMerchantId=654321' \
  --data-urlencode 'masterMerchantAcquirerBin=5200'

Response samples

{
  "key": "*/type:entity/module:ctpe/processing:risk/risk:threeDSecure/config:threeDType",
  "value": "3DSecure"
}

Generate EBICS PDF file

The call generates an EBICS PDF to receive the link for a chosen merchant account. Before executing the call, make sure the merchant account is working with EBICS.

Use the method GET to request the PDF URL without changing the settings for the three parameters listed in the Data Parameters table.

Note. This functionality is not fully implemented.

Endpoints

POST/merchantAccounts/{merchantAccountId}/ebics
Check the enrollment status using the merchant account ID

URL parameters

merchantAccountIdrequired
[a-f 0-9]32
The ID of the merchant account.

Data parameters

initializerequired
true/falseBoolean
Parameter to activate EBICS PDF generation.
dtausActivatedConditional
true/falseBoolean
If this parameter is not sent in the request or is sent with the value "false", then the PDF URL is returned signed.
If this parameter is sent with the value "true", then the PDF URL is returned unsigned.
mt940ActivatedConditional
true/falseBoolean
If this parameter is not sent in the request or is sent with the value "false", then the PDF URL is returned signed.
If this parameter is sent with the value "true", then the PDF URL is returned unsigned.

Success response

200: OKThe request was successful.
ebics
true/falseBoolean
The EBICS info object.
initialized
true/falseBoolean
The status of EBICS PDF generation.
dtausActivated
true/falseBoolean
The status of the DTAUS.
mt940Activated
true/falseBoolean
The status of the MT940.
pdfURL
the URLBoolean
The PDF URL.

Error response

200Used to tunnel errors. Check the error message.
POST/merchantAccounts/{merchantAccountId}/ebics

Response samples

{
  "ebics": {
    "initialized": "true",
    "dtausActivated": "false",
    "mt940Activated": "false",
    "pdfURL": "…"
  }
}

Detach All Attached Merchant Accounts

The call detaches all merchant accounts that are attached to a specific entity.

Endpoints

DELETE/psps/{pspid}/attachedMerchantAccounts
Option 1. Detach all attached merchant accountsusing pspID
DELETE/divisions/{divisionid}/attachedMerchantAccounts
Option 2. Detach all attached merchant accountsusing divisionID
DELETE/merchants/{merchantid}/attachedMerchantAccounts
Option 3. Detach all attached merchant accountsusing merchantID
DELETE/channels/{channelId}/attachedMerchantAccounts
Option 4. Detach all attached merchant accounts using channelID

URL parameters

pspIdrequired for option 1
[a-f 0-9]32
The ID of the PSP.
divisionIdrequired for option 2
[a-f 0-9]32
The ID of the division.
merchantIdrequired for option 3
[a-f 0-9]32
The ID of the merchant.
channelIdrequired for option 4
[a-f 0-9]32
The ID of the channel.

Data parameters

No parameters required

Success response

200: OKThe request was successful.

No response body

Error response

200: OKUsed to tunnel errors. Check the error message.
DELETE/psps/{pspid}/attachedMerchantAccounts
DELETE/divisions/{divisionid}/attachedMerchantAccounts
DELETE/merchants/{merchantid}/attachedMerchantAccounts
DELETE/channels/{channelId}/attachedMerchantAccounts

Request sample

curl -X DELETE \
  'https://eu-test.oppwa.com/bip/webapi/v1/channels/{channelId}/attachedMerchantAccounts' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{}

Delete All Owned Merchant Accounts

The call deletes all owned merchant accounts that are created for a specific entity.

Endpoints

DELETE/psps/{pspid}/ownedMerchantAccounts
Option 1. Delete all owned merchant accountsusing pspID.
DELETE/divisions/{divisionid}/ownedMerchantAccounts
Option 2. Delete all owned merchant accountsusing divisionID.
DELETE/merchants/{merchantid}/ownedMerchantAccounts
Option 3. Delete all owned merchant accountsusing merchantID.
DELETE/channels/{channelId}/ownedMerchantAccounts
Option 4. Delete all owned merchant accounts using channelID.

URL parameters

pspIdrequired for option 1
[a-f 0-9]32
The ID of the PSP.
divisionIdrequired for option 2
[a-f 0-9]32
The ID of the division.
merchantIdrequired for option 3
[a-f 0-9]32
The ID of the merchant.
channelIdrequired for option 4
[a-f 0-9]32
The ID of the channel.

Data parameters

No parameters required

Success response

200: OKThe request was successful.

Error response

200: OKUsed to tunnel errors. Check the error message.
DELETE/psps/{pspid}/ownedMerchantAccounts
DELETE/divisions/{divisionid}/ownedMerchantAccounts
DELETE/merchants/{merchantid}/ownedMerchantAccounts
DELETE/channels/{channelId}/ownedMerchantAccounts

Request sample

curl -X DELETE \
  'https://eu-test.oppwa.com/bip/webapi/v1/channels/{channelId}/ownedMerchantAccounts' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{}

RiRo settings operations

Get RiRo setting value
GET/psps/{pspid}/setting
GET/divisions/{divisionsid}/setting
GETmerchants/{merchantId}/setting
GETchannels/{channelid}/setting
Update RiRo setting value
POST/psps/{pspid}/setting
POST/divisions/{divisionsid}/setting
POSTmerchants/{merchantId}/setting
POSTchannels/{channelid}/setting

Get RiRo setting value

The call views the RiRo settings. Check the Keys for configuring RiRo settings for the complete list of keys.

Endpoints

GETpsps/{pspid}/setting
View the value of a RiRo setting using the ID of the entity:
GETdivisions/{divisionsid}/setting
GETmerchants/{merchantId}/setting
GETchannels/{channelid}/setting

URL parameters

pspIdrequired
[a-f 0-9]32
The ID of the PSP.
divisionIdrequired
[a-f 0-9]32
The ID of the division.
merchantIdrequired
[a-f 0-9]32
The ID of the merchant.
channelIdrequired
[a-f 0-9]32
The ID of the channel.

Data parameters

keyrequired
The RiRo key, for which the value will be queried.

Success response

200: OKThe request was successful.
key
The RiRo key, for which the value is queried.
valueType
The value type can be Boolean, Number, String, or Stringlist
value
The new value for the RiRo key setting.

Error response

200.*.*Used to tunnel errors – check the error message.
GETpsps/{pspid}/setting
GETdivisions/{divisionsid}/setting
GETmerchants/{merchantId}/setting
GETchannels/{channelid}/setting

Request sample

curl -X GET \
  'https://eu-test.oppwa.com/bip/webapi/v1/merchants/{merchantId}/setting?key=%2A/type:entity/module:frontend/processing:frontend/frontend:DD/DD:active' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "key": "*/type:entity/module:frontend/processing:frontend/frontend:CC/CC:active",
  "value": ""
}

Update RiRo setting value

The call allows modification of the RiRo settings. Check the Keys for configuring RiRo settings for the complete list of keys.

Endpoints

POSTpsps/{pspid}/setting
Modify the value of a RiRo setting using the ID of the entity:
POSTdivisions/{divisionsid}/setting
POSTmerchants/{merchantId}/setting
POSTchannels/{channelid}/setting

URL parameters

pspIdrequired
[a-f 0-9]32
The ID of the PSP.
divisionIdrequired
[a-f 0-9]32
The ID of the division.
merchantIdrequired
[a-f 0-9]32
The ID of the merchant.
channelIdrequired
[a-f 0-9]32
The ID of the channel.

Data parameters

keyrequired
The RiRo key, for which the value is queried.
valuerequired
The new value for the RiRo key setting.

Success response

200: OKThe request was successful.
key
The RiRo key, for which the value is queried.
valueType
The value type can be one of the following values: Boolean, Number, String, or Stringlist
value
The new value for the RiRo key setting.

Error response

200.*.*Used to tunnel errors – check the error message.
POSTpsps/{pspid}/setting
POSTdivisions/{divisionsid}/setting
POSTmerchants/{merchantId}/setting
POSTchannels/{channelid}/setting

Request sample

curl -X POST \
  'https://eu-test.oppwa.com/bip/webapi/v1/merchants/{merchantId}/setting' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>' \
  -H 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \
  --data-urlencode 'key=*/type:entity/module:frontend/processing:frontend/frontend:DD/DD:active' \
  --data-urlencode 'value=false'

Response samples

{
  "key": "*/type:entity/module:frontend/processing:frontend/frontend:CC/CC:active",
  "value": "false"
}

API Tokens operations

Get API Token List for Merchant
GETmerchants/{merchantId}/apiTokens
Get API Token
GETapiTokens/{apiTokenId}
Create API Token for Merchant
POSTmerchants/{merchantId}/apiTokens
Suspend API Token
POSTapiTokens/{apiTokenId}/suspend
Activate API Token
POSTapiTokens/{apiTokenId}/activate
Update API Token
POSTapiTokens/{apiTokenId}
Delete API Token
DELETEapiTokens/{apiTokenId}

Get API Token List for Merchant

The call lists the information about all API Tokens that were created at the merchant specified by merchant id.

Endpoints

GETmerchants/{merchantId}/apiTokens
List the API tokens using merchant ID.

URL parameters

merchantIdrequired
[a-f 0-9]32
The ID of the merchant.

Data parameters

No parameters are required

Success response

200: OKThe request was successful.
apiTokens
the array of tokens
id
[a-f 0-9]32
The ID of the api token
alias
[A-Z a-z 0-9],[-_]40
The name of the api token to be listed.
createdTime
YYYY-MM-DD HH:mm:ss
Time when token was created.
lastDigits
[A-Z a-z 0-9]*5,=6
Last digits of the api token.
lastUsedTime
YYYY-MM-DD HH:mm:ss
Time when the token was last used.
state
ACTIVE/SUSPENDED/DELETED
Current state of the api token.

Error response

200.*.*Used to tunnel errors. Check the error message.
GETmerchants/{merchantId}/apiTokens

Request sample

curl -X GET \
  'https://eu-test.oppwa.com/bip/webapi/v1/merchants/{merchantId}/apiTokens' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "apiTokens": [
    {
      "alias": "opp_merchant_XML",
      "createdTime": "2017-07-24 08:38:03",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd98",
      "lastDigits": "R5NzI=",
      "lastUsedTime": "1970-01-01 00:00:00",
      "state": "ACTIVE"
    },
    {
      "alias": "SYSTEM_OPP_Merchant_2",
      "createdTime": "2026-02-24 17:31:07",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd99",
      "lastDigits": "lDYmg=",
      "lastUsedTime": "1970-01-01 00:00:00",
      "state": "ACTIVE"
    },
    {
      "alias": "SYSTEM_OPP_Merchant_4",
      "createdTime": "2026-03-05 15:50:42",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd100",
      "lastDigits": "UyREA=",
      "lastUsedTime": "1970-01-01 00:00:00",
      "state": "ACTIVE"
    },
    {
      "alias": "SYSTEM_OPP_Merchant_1",
      "createdTime": "2026-02-24 10:01:57",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd101",
      "lastDigits": "pRUlU=",
      "lastUsedTime": "1970-01-01 00:00:00",
      "state": "ACTIVE"
    },
    {
      "alias": "SYSTEM_OPP_Merchant_3",
      "createdTime": "2026-03-04 13:55:59",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd102",
      "lastDigits": "hIVWQ=",
      "lastUsedTime": "1970-01-01 00:00:00",
      "state": "ACTIVE"
    }
  ]
}

Get API Token

The call provides the information about the API token specified by ID.

Endpoints

GET/apiTokens/{apiTokenId}
Get an API token using the token ID.

URL parameters

apiTokenIdrequired
[a-f 0-9]32
The ID of the token.

Data parameters

No parameters are required

Success response

200: OKThe request was successful.
id
[a-f 0-9]32
The ID of the api token
alias
[A-Z a-z 0-9],[-_]40
The name of the api token to be listed.
createdTime
YYYY-MM-DD HH:mm:ss
Time when token was created.
lastDigits
[A-Z a-z 0-9]*5,=6
Last digits of the api token.
lastUsedTime
YYYY-MM-DD HH:mm:ss
Time when the token was last used.
state
ACTIVE/SUSPENDED/DELETED
Current state of the api token.

Error response

200.*.*Used to tunnel errors. Check the error message.
GET/apiTokens/{apiTokenId}

Request sample

curl -X GET \
  'https://eu-test.oppwa.com/bip/webapi/v1/apiTokens/{apiTokenId}' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "apiToken": {
    "alias": "opp_merchant_XML",
    "createdTime": "2017-07-24 08:38:03",
    "id": "ab12cd34ef56ab12cd34ef56ab12cd98",
    "lastDigits": "R5NzI=",
    "lastUsedTime": "1970-01-01 00:00:00",
    "state": "ACTIVE"
  }
}

Create API Token for Merchant

The call adds a new api token for a merchant

Endpoints

POST/merchants/{merchantId}/apiTokens
Add an API token using merchant ID.

URL parameters

merchantIdrequired
[a-f 0-9]32
The ID of the merchant.

Data parameters

No body

Success response

201: CreatedEntity was successfully created.
id
[a-f 0-9]32
The ID of the api token
alias
[A-Z a-z 0-9],[-_]40
The name of the api token to be listed.
apiBearerToken
[A-Z a-z 0-9 =]
Api tokenthat should be sent for transaction processing.
createdTime
YYYY-MM-DD HH:mm:ss
Time when token was created.
lastDigits
[A-Z a-z 0-9 =]6
Last digits of the api token.
lastUsedTime
YYYY-MM-DD HH:mm:ss
Time when the token was last used.
state
ACTIVE/SUSPENDED/DELETED
Current state of the api token.

Error response

200.*.*Used to tunnel errors. Check the error message.
error
Error marker and container for the following field.
message
Human readable description of the error.
POST/merchants/{merchantId}/apiTokens

Request sample

curl -X POST \
  'https://eu-test.oppwa.com/bip/webapi/v1/merchants/{merchantId}/apiTokens' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "apiToken": {
    "alias": "SYSTEM_OPP_Merchant_6",
    "apiBearerToken": "<api-bearer-token>",
    "createdTime": "2026-03-23 09:21:23",
    "id": "ab12cd34ef56ab12cd34ef56ab12cd103",
    "lastDigits": "JMTUs=",
    "lastUsedTime": "1970-01-01 00:00:00",
    "state": "ACTIVE"
  }
}

Suspend API Token

The call suspend an api token

Endpoints

POSTapiTokens/{apiTokenId}/suspend

URL parameters

apiTokenIdrequired
[a-f 0-9]32
The ID of the API token.

Data parameters

No body

Success response

200: SuccessToken was suspended
id
[a-f 0-9]32
The ID of the api token
alias
[A-Z a-z 0-9],[-_]40
The name of the api token to be listed.
createdTime
YYYY-MM-DD HH:mm:ss
Time when token was created.
lastDigits
[A-Z a-z 0-9]*5,=6
Last digits of the api token.
lastUsedTime
YYYY-MM-DD HH:mm:ss
Time when the token was last used.
state
SUSPENDED
Current state of the api token.

Error response

200.*.*Used to tunnel errors. Check the error message.
error
Error marker and container for the following field.
message
Human readable description of the error.
POSTapiTokens/{apiTokenId}/suspend

Request sample

curl -X POST \
  'https://eu-test.oppwa.com/bip/webapi/v1/apiTokens/{apiTokenId}/suspend' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "apiToken": {
    "alias": "SYSTEM_OPP_Merchant_6",
    "createdTime": "2026-03-23 09:21:23",
    "id": "ab12cd34ef56ab12cd34ef56ab12cd103",
    "lastDigits": "JMTUs=",
    "lastUsedTime": "1970-01-01 00:00:00",
    "state": "SUSPENDED"
  }
}

Activate API Token

The call to activate an API token

Endpoints

POSTapiTokens/{apiTokenId}/activate

URL parameters

apiTokenIdrequired
[a-f 0-9]32
The ID of the API token.

Data parameters

No body

Success response

200: SuccessToken was activated
id
[a-f 0-9]32
The ID of the api token
alias
[A-Z a-z 0-9],[-_]40
The name of the api token to be listed.
createdTime
YYYY-MM-DD HH:mm:ss
Time when token was created.
lastDigits
[A-Z a-z 0-9]*5,=6
Last digits of the api token.
lastUsedTime
YYYY-MM-DD HH:mm:ss
Time when the token was last used.
state
ACTIVE
Current state of the api token.

Error response

200.*.*Used to tunnel errors. Check the error message.
error
Error marker and container for the following field.
message
Human readable description of the error.
POSTapiTokens/{apiTokenId}/activate

Request sample

curl -X POST \
  'https://eu-test.oppwa.com/bip/webapi/v1/apiTokens/{apiTokenId}/activate' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "apiToken": {
    "alias": "SYSTEM_OPP_Merchant_6",
    "createdTime": "2026-03-23 09:21:23",
    "id": "ab12cd34ef56ab12cd34ef56ab12cd103",
    "lastDigits": "JMTUs=",
    "lastUsedTime": "1970-01-01 00:00:00",
    "state": "ACTIVE"
  }
}

Update API Token

The call to update an api token

Endpoints

POSTapiTokens/{apiTokenId}

URL parameters

apiTokenIdrequired
[a-f 0-9]32
The ID of the API token.

Data parameters

aliasrequired
[A-Z a-z 0-9], [-_]40
The new alias/name of the API token.

Success response

200: SuccessToken was updated
id
[a-f 0-9]32
The ID of the api token
alias
[A-Z a-z 0-9],[-_]40
The name of the api token to be listed.
createdTime
YYYY-MM-DD HH:mm:ss
Time when token was created.
lastDigits
[A-Z a-z 0-9]*5,=6
Last digits of the api token.
lastUsedTime
YYYY-MM-DD HH:mm:ss
Time when the token was last used.
state
ACTIVE/SUSPENDED
Current state of the api token.

Error response

200.*.*Used to tunnel errors. Check the error message.
error
Error marker and container for the following field.
message
Human readable description of the error.
POSTapiTokens/{apiTokenId}

Request sample

curl -X POST \
  'https://eu-test.oppwa.com/bip/webapi/v1/apiTokens/{apiTokenId}' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>' \
  -H 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \
  --data-urlencode 'alias=newalias'

Response samples

{
  "apiToken": {
    "alias": "SYSTEM_OPP_Merchant_6",
    "createdTime": "2026-03-23 09:21:23",
    "id": "ab12cd34ef56ab12cd34ef56ab12cd103",
    "lastDigits": "JMTUs=",
    "lastUsedTime": "1970-01-01 00:00:00",
    "state": "ACTIVE"
  }
}

Delete API Token

The call to delete an api token

Note. Only suspended tokens can be deleted.

Endpoints

DELETEapiTokens/{apiTokenId}

URL parameters

apiTokenIdrequired
[a-f 0-9]32
The ID of the API token.

Success response

200: SuccessToken was deleted

Error response

200.*.*Used to tunnel errors. Check the error message.
error
Error marker and container for the following field.
message
Human readable description of the error.
DELETEapiTokens/{apiTokenId}

Request sample

curl -X DELETE \
  'https://eu-test.oppwa.com/bip/webapi/v1/apiTokens/{apiTokenId}' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "error": {
    "message": "Error deleting API token: CCS returned unexpected status code (400) - API_TOKEN_INVALID_DELETE_STATE - Only suspended tokens can be deleted"
  }
}

Webhook operations

Add Webhook
POST/psps/{pspid}/webhooks
POST/divisions/{divisionsid}/webhooks
POST/merchants/{merchantid}/webhooks
POST/channels/{channelId}/webhooks
Get Webhook
GET/psps/{pspId}/webhooks/{webhookId}
GET/divisions/{divisionsId}/webhooks/{webhookid}
GET/merchants/{merchantId}/webhooks/{webhookId}
GET/channels/{channelId}/webhooks/{webhookId}
Edit Webhook
POST/psps/{pspId}/webhooks/{webhookId}
POST/divisions/{divisionsId}/webhooks/{webhookid}
POST/merchants/{merchantId}/webhooks/{webhookId}
POST/channels/{channelId}/webhooks/{webhookId}
List Webhooks
GET/psps/{pspid}/webhooks
GET/divisions/{divisionsid}/webhooks
GET/merchants/{merchantid}/webhooks
GET/channels/{channelId}/webhooks
Delete Webhook
DELETE/psps/{pspId}/webhooks/{webhookId}
DELETE/divisions/{divisionsId}/webhooks/{webhookid}
DELETE/merchants/{merchantId}/webhooks/{webhookId}
DELETE/channels/{channelId}/webhooks/{webhookId}
Validate Webhook
GET/psps/{pspId}/webhooks/{webhookId}/validate
GET/divisions/{divisionsId}/webhooks/{webhookid}/validate
GET/merchants/{merchantId}/webhooks/{webhookId}/validate
GET/channels/{channelId}/webhooks/{webhookId}/validate
Update Webhook State
POST/psps/{pspId}/webhooks/{webhookId}/state
POST/divisions/{divisionsId}/webhooks/{webhookid}/state
POST/merchants/{merchantId}/webhooks/{webhookId}/state
POST/channels/{channelId}/webhooks/{webhookId}/state

Add Webhook

The call adds a webhook.

The webhook can be created at PSP, division, merchant, or channel levels.

Endpoints

POST/PSPs/{pspId}/webhooks
Option 1. Add a webhook using psp ID.
POST/divisions/{divisionsId}/webhooks
Option 2. Add a webhook using division ID.
POST/merchants/{merchantId}/webhooks
Option 3. Add a webhook using merchant ID.
POST/channels/{channelId}/webhooks
Option 4. Add a webhook using channel ID.

URL parameters

pspIdrequired for option 1
[a-f 0-9]32
The ID of the PSP.
divisionIdrequired for option 2
[a-f 0-9]32
The ID of the division.
merchantIdrequired for option 3
[a-f 0-9]32
The ID of the merchant.
channelIdrequired for option 4
[a-f 0-9]32
The ID of the channel.

Data parameters

endpoint
starts with http or https
The public endpoint that will receive the webhook notifications.
notificationTypes.{group}
Events to subscribe to.
Possible groups and their corresponding event values are:
payments - ALL,AD,PA,CB,CD,CP,CR,DB,RB,RC,RF,RL,RV,CL,CT,PO
registrations - ALL
schedules - ALL,SD,RS,DS
risks - ALL,MD,EA,RI,3D,SA,EN,IC,DP,CG,TG,SF,IS,VD,DV,AF,GK,RD,TM,FT,KT,AR,AL,PL,FN,FZ,RE,RX,AC,CS,FO,EX,SE
Restrictions:
ALL cannot be combined with other values.
Multiple event values can be combined using commas, e.g. notificationTypes.payments=PA,CB.
At least one event must be present.
preset
Possible values are:
ALL - full payload
NON_CUSTOMER_DATA - exclude sensitive fields
wrapper
(Optional) Format of the payload.
Possible values are:
(default) - hex string
JSON - wrapped in JSON
secret
[0-9 a-f A-F]64
(Optional) A 64-character hex string used to encrypt the payload. If empty, a random secret is generated.
emails
(Optional) One or more email addresses to receive daily failure summaries. Use commas to separate email addresses.

Success response

201: CreatedWebhook was successfully created.

Response is a webhook object with the following structure:

id
[a-f 0-9]32
The webhook ID.
entityId
[a-f 0-9]32
The entity (PSP, division, merchant, or channel) ID, where the webhook is attached to.
confirmed
false/true
The flag indicating whether the webhook is validated. For a newly-created webhook, the default value is false.
active
false/true
The flag indicating whether the webhook is active. For a newly-created webhook, the default value is false.
endpoint
starts with http or https
The public endpoint that will receive the webhook notifications.
notificationTypes.{group}
Subscribed events.
Each group is an array in which possible values are:
payments - ALL,AD,PA,CB,CD,CP,CR,DB,RB,RC,RF,RL,RV,CL,CT,PO
registrations - ALL
schedules - ALL,SD,RS,DS
risks - ALL,MD,EA,RI,3D,SA,EN,IC,DP,CG,TG,SF,IS,VD,DV,AF,GK,RD,TM,FT,KT,AR,AL,PL,FN,FZ,RE,RX,AC,CS,FO,EX,SE
preset
Possible values are:
ALL - full payload
NON_CUSTOMER_DATA - exclude sensitive fields
wrapper
Format of the payload.
Possible values are:
(default) - hex string
JSON - wrapped in JSON
secret
[0-9 a-f A-F]64
A 64-character hex string used to encrypt the payload.
emails
Array of email addresses to receive daily failure summaries.

The newly added webhook is inactive by default. Use Update Webhook State to activate it.

Error response

200.*.*Used to tunnel errors. Check the error message.
POST/PSPs/{pspId}/webhooks
POST/divisions/{divisionsId}/webhooks
POST/merchants/{merchantId}/webhooks
POST/channels/{channelId}/webhooks

Request sample

curl -X POST \
  'https://eu-test.oppwa.com/bip/webapi/v1/channels/{channelId}/webhooks' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>' \
  -H 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \
  --data-urlencode 'endpoint=https://example.com' \
  --data-urlencode 'notificationTypes.payments=PA,CP,DB' \
  --data-urlencode 'notificationTypes.registrations=ALL' \
  --data-urlencode 'preset=ALL' \
  --data-urlencode 'emails=alerts@example.com'

Response samples

{
  "webhook": {
    "active": false,
    "confirmed": false,
    "emails": [
      "alerts@example.com"
    ],
    "entityId": "ab12cd34ef56ab12cd34ef56ab12cd104",
    "id": "ab12cd34ef56ab12cd34ef56ab12cd105",
    "notificationTypes": {
      "payments": [
        "PA",
        "CP",
        "DB"
      ],
      "registrations": [
        "ALL"
      ]
    },
    "preset": "ALL",
    "secret": "<64-character-hex-secret>",
    "endpoint": "https://example.com"
  }
}

Get Webhook

The call gets information about an existing webhook.

The webhook can be retrieved at PSP, division, merchant, or channel levels.

Endpoints

GET/psps/{pspId}/webhooks/{webhookId}
Option 1. Get a webhook using PSP ID and webhook ID.
GET/divisions/{divisionsId}/webhooks/{webhookid}
Option 2. Get a webhook using division ID and webhook ID.
GET/merchants/{merchantId}/webhooks/{webhookId}
Option 3. Get a webhook using merchant ID and webhook ID.
GET/channels/{channelId}/webhooks/{webhookId}
Option 4. Get a webhook using channel ID and webhook ID.

URL parameters

pspIdThe ID of the PSP.[a-f 0-9]32Required for Option 1
divisionIdThe ID of the division.[a-f 0-9]32Required for Option 2
merchantIdThe ID of the merchant.[a-f 0-9]32Required for Option 3
channelIdThe ID of the channel.[a-f 0-9]32Required for Option 4
webhookIdThe ID of the webhook.[a-f 0-9]32Required

Data parameters

No parameters required.

Success response

200: OKThe request was successful.

Response is a webhook object with the following structure:

idThe webhook ID.[a-f 0-9]32
entityIdThe entity (PSP, division, merchant, or channel) ID, where the webhook is attached to.[a-f 0-9]32
confirmedThe flag indicating whether the webhook is validated.false/true-
activeThe flag indicating whether the webhook is active.false/true-
endpointThe public endpoint that will receive the webhook notifications.starts with http or https-
notificationTypes.{group}Subscribed events.
Each group is an array in which possible values are:
payments - ALL,AD,PA,CB,CD,CP,CR,DB,RB,RC,RF,RL,RV,CL,CT,PO
registrations - ALL
schedules - ALL,SD,RS,DS
risks - ALL,MD,EA,RI,3D,SA,EN,IC,DP,CG,TG,SF,IS,VD,DV,AF,GK,RD,TM,FT,KT,AR,AL,PL,FN,FZ,RE,RX,AC,CS,FO,EX,SE		--
presetPossible values are:
ALL - full payload
NON_CUSTOMER_DATA - exclude sensitive fields		--
wrapperFormat of the payload.
Possible values are:
(default) - hex string
JSON - wrapped in JSON		--
secretA 64-character hex string used to encrypt the payload.[0-9 a-f A-F]64
emailsArray of email addresses to receive daily failure summaries.--

Response Example

Error response

200.*.*Used to tunnel errors. Check the error message.

Example

GET/psps/{pspId}/webhooks/{webhookId}
GET/divisions/{divisionsId}/webhooks/{webhookid}
GET/merchants/{merchantId}/webhooks/{webhookId}
GET/channels/{channelId}/webhooks/{webhookId}

Request sample

curl -X GET \
  'https://eu-test.oppwa.com/bip/webapi/v1/channels/{channelId}/webhooks/{webhookId}' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "webhook": {
    "active": false,
    "confirmed": false,
    "emails": [
      "alerts@example.com"
    ],
    "entityId": "ab12cd34ef56ab12cd34ef56ab12cd104",
    "id": "ab12cd34ef56ab12cd34ef56ab12cd105",
    "notificationTypes": {
      "payments": [
        "PA",
        "CP",
        "DB"
      ],
      "registrations": [
        "ALL"
      ]
    },
    "preset": "ALL",
    "secret": "<64-character-hex-secret>",
    "endpoint": "https://example.com"
  }
}

Edit Webhook

The call edits a webhook.

The webhook can be edited at PSP, division, merchant, or channel levels.

Endpoints

POST/psps/{pspId}/webhooks/{webhookId}
Option 1. Add a webhook using psp ID and webhook ID.
POST/divisions/{divisionsId}/webhooks/{webhookId}
Option 2. Add a webhook using division ID and webhook ID.
POST/merchants/{merchantId}/webhooks/{webhookId}
Option 3. Add a webhook using merchant ID and webhook ID.
POST/channels/{channelId}/webhooks/{webhookId}
Option 4. Add a webhook using channel ID and webhook ID.

URL parameters

pspIdThe ID of the PSP.[a-f 0-9]32Required for Option 1
divisionIdThe ID of the division.[a-f 0-9]32Required for Option 2
merchantIdThe ID of the merchant.[a-f 0-9]32Required for Option 3
channelIdThe ID of the channel.[a-f 0-9]32Required for Option 4
webhookIdThe ID of the webhook.[a-f 0-9]32Required

Data parameters

If the request is submitted with parameters set to empty spaces, for example, name=<single space>, this deletes the previous values and leaves the fields blank.
The parameters not included in the request are not changed. To avoid nullifying valid values, skip the parameters that do not require an update.

endpointThe public endpoint that will receive the webhook notifications.starts with http or https-
notificationTypes.{group}Events to subscribe to.
Possible groups and their corresponding event values are:
payments - ALL,AD,PA,CB,CD,CP,CR,DB,RB,RC,RF,RL,RV,CL,CT,PO
registrations - ALL
schedules - ALL,SD,RS,DS
risks - ALL,MD,EA,RI,3D,SA,EN,IC,DP,CG,TG,SF,IS,VD,DV,AF,GK,RD,TM,FT,KT,AR,AL,PL,FN,FZ,RE,RX,AC,CS,FO,EX,SE
Restrictions:
ALL cannot be combined with other values.
Multiple event values can be combined using commas, e.g. notificationTypes.payments=PA,CB.
At least one event must be present.		--
presetPossible values are:
ALL - full payload
NON_CUSTOMER_DATA - exclude sensitive fields		--
wrapperFormat of the payload.
Possible values are:
(default) - hex string
JSON - wrapped in JSON		--
secretA 64-character hex string used to encrypt the payload. If empty, a random secret is generated.[0-9 a-f A-F]64
emailsOne or more email addresses to receive daily failure summaries. Use commas to separate email addresses.--

Success response

200: OKThe request was successful.

Response is a webhook object with the following structure:

idThe webhook ID.[a-f 0-9]32
entityIdThe entity (PSP, division, merchant, or channel) ID, where the webhook is attached to.[a-f 0-9]32
confirmedThe flag indicating whether the webhook is validated.false/true-
activeThe flag indicating whether the webhook is active.false/true-
endpointThe public endpoint that will receive the webhook notifications.starts with http or https-
notificationTypes.{group}Subscribed events.
Each group is an array in which possible values are:
payments - ALL,AD,PA,CB,CD,CP,CR,DB,RB,RC,RF,RL,RV,CL,CT,PO
registrations - ALL
schedules - ALL,SD,RS,DS
risks - ALL,MD,EA,RI,3D,SA,EN,IC,DP,CG,TG,SF,IS,VD,DV,AF,GK,RD,TM,FT,KT,AR,AL,PL,FN,FZ,RE,RX,AC,CS,FO,EX,SE		--
presetPossible values are:
ALL - full payload
NON_CUSTOMER_DATA - exclude sensitive fields		--
wrapperFormat of the payload.
Possible values are:
(default) - hex string
JSON - wrapped in JSON		--
secretA 64-character hex string used to encrypt the payload.[0-9 a-f A-F]64
emailsArray of email addresses to receive daily failure summaries.--

Example

Error response

200.*.*Used to tunnel errors. Check the error message.

Example

POST/psps/{pspId}/webhooks/{webhookId}
POST/divisions/{divisionsId}/webhooks/{webhookId}
POST/merchants/{merchantId}/webhooks/{webhookId}
POST/channels/{channelId}/webhooks/{webhookId}

Request sample

curl -X POST \
  'https://eu-test.oppwa.com/bip/webapi/v1/channels/{channelId}/webhooks/{webhookId}' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>' \
  -H 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \
  --data-urlencode 'notificationTypes.payments=PA,DB' \
  --data-urlencode 'notificationTypes.registrations=' \
  --data-urlencode 'preset=NON_CUSTOMER_DATA' \
  --data-urlencode 'wrapper=JSON'

Response samples

{
  "webhook": {
    "active": false,
    "confirmed": false,
    "emails": [
      "alerts@example.com"
    ],
    "entityId": "ab12cd34ef56ab12cd34ef56ab12cd104",
    "id": "ab12cd34ef56ab12cd34ef56ab12cd105",
    "notificationTypes": {
      "payments": [
        "PA",
        "DB"
      ]
    },
    "preset": "NON_CUSTOMER_DATA",
    "secret": "<64-character-hex-secret>",
    "endpoint": "https://example.com",
    "wrapper": "JSON"
  }
}

List Webhooks

The call allows listing information about existing webhooks.

The webhooks can be retrieved at PSP, division, merchant, or channel levels.

Endpoints

GET/psps/{pspId}/webhooks
Option 1. List webhooks using PSP ID.
GET/divisions/{divisionsId}/webhooks
Option 2. List webhooks using division ID.
GET/merchants/{merchantId}/webhooks
Option 3. List webhooks using merchant ID.
GET/channels/{channelId}/webhooks
Option 4. List webhooks using channel ID.

URL parameters

pspIdThe ID of the PSP.[a-f 0-9]32Required for Option 1
divisionIdThe ID of the division.[a-f 0-9]32Required for Option 2
merchantIdThe ID of the merchant.[a-f 0-9]32Required for Option 3
channelIdThe ID of the channel.[a-f 0-9]32Required for Option 4

Data parameters

No parameters required.

Success response

200: OKThe request was successful.

Response is a webhooks array, where each element has the following structure:

idThe webhook ID.[a-f 0-9]32
entityIdThe entity (PSP, division, merchant, or channel) ID, where the webhook is attached to.[a-f 0-9]32
confirmedThe flag indicating whether the webhook is validated.false/true-
activeThe flag indicating whether the webhook is active.false/true-
endpointThe public endpoint that will receive the webhook notifications.starts with http or https-
notificationTypes.{group}Subscribed events.
Each group is an array in which possible values are:
payments - ALL,AD,PA,CB,CD,CP,CR,DB,RB,RC,RF,RL,RV,CL,CT,PO
registrations - ALL
schedules - ALL,SD,RS,DS
risks - ALL,MD,EA,RI,3D,SA,EN,IC,DP,CG,TG,SF,IS,VD,DV,AF,GK,RD,TM,FT,KT,AR,AL,PL,FN,FZ,RE,RX,AC,CS,FO,EX,SE		--
presetPossible values are:
ALL - full payload
NON_CUSTOMER_DATA - exclude sensitive fields		--
wrapperFormat of the payload.
Possible values are:
(default) - hex string
JSON - wrapped in JSON		--
secretA 64-character hex string used to encrypt the payload.[0-9 a-f A-F]64
emailsArray of email addresses to receive daily failure summaries.--

Response Example

GET/psps/{pspId}/webhooks
GET/divisions/{divisionsId}/webhooks
GET/merchants/{merchantId}/webhooks
GET/channels/{channelId}/webhooks

Request sample

curl -X GET \
  'https://eu-test.oppwa.com/bip/webapi/v1/channels/{channelId}/webhooks' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "webhooks": [
    {
      "active": false,
      "confirmed": false,
      "emails": [
        "alerts@example.com"
      ],
      "entityId": "ab12cd34ef56ab12cd34ef56ab12cd104",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd105",
      "notificationTypes": {
        "payments": [
          "PA",
          "CP",
          "DB"
        ],
        "registrations": [
          "ALL"
        ]
      },
      "preset": "ALL",
      "secret": "<64-character-hex-secret>",
      "endpoint": "https://example.com"
    }
  ]
}

Delete Webhook

The call deletes an existing webhook.

The webhook can be deleted at PSP, division, merchant, or channel levels.

Endpoints

DELETE/psps/{pspId}/webhooks/{webhookId}
Option 1. Delete a webhook using PSP ID and webhook ID.
DELETE/divisions/{divisionsId}/webhooks/{webhookid}
Option 2.Delete a webhook using division ID and webhook ID.
DELETE/merchants/{merchantId}/webhooks/{webhookId}
Option 3.Delete a webhook using merchant ID and webhook ID.
DELETE/channels/{channelId}/webhooks/{webhookId}
Option 4.Delete a webhook using channel ID and webhook ID.

URL parameters

pspIdThe ID of the PSP.[a-f 0-9]32Required for Option 1
divisionIdThe ID of the division.[a-f 0-9]32Required for Option 2
merchantIdThe ID of the merchant.[a-f 0-9]32Required for Option 3
channelIdThe ID of the channel.[a-f 0-9]32Required for Option 4
webhookIdThe ID of the webhook.[a-f 0-9]32Required

Data parameters

No parameters required.

Success response

200: OKThe request was successful.

Response Example

Error response

200.*.*Used to tunnel errors. Check the error message.

Example

DELETE/psps/{pspId}/webhooks/{webhookId}
DELETE/divisions/{divisionsId}/webhooks/{webhookid}
DELETE/merchants/{merchantId}/webhooks/{webhookId}
DELETE/channels/{channelId}/webhooks/{webhookId}

Request sample

curl -X DELETE \
  'https://eu-test.oppwa.com/bip/webapi/v1/channels/{channelId}/webhooks/{webhookId}' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{}

Validate Webhook

The call sends a test webhook request to the registered endpoint. If the request is successful (2xx), the webhook is marked as confirmed.

Use this endpoint if you only want to validate your endpoint, without activating it. To validate and activate at the same time, use Update Webhook State.

The webhook can be validated at PSP, division, merchant, or channel levels.

Endpoints

GET/psps/{pspId}/webhooks/{webhookId}/validate
Option 1. Validate a webhook using PSP ID and webhook ID.
GET/divisions/{divisionsId}/webhooks/{webhookid}/validate
Option 2. Validate a webhook using division ID and webhook ID.
GET/merchants/{merchantId}/webhooks/{webhookId}/validate
Option 3. Validate a webhook using merchant ID and webhook ID.
GET/channels/{channelId}/webhooks/{webhookId}/validate
Option 4. Validate a webhook using channel ID and webhook ID.

URL parameters

pspIdThe ID of the PSP.[a-f 0-9]32Required for Option 1
divisionIdThe ID of the division.[a-f 0-9]32Required for Option 2
merchantIdThe ID of the merchant.[a-f 0-9]32Required for Option 3
channelIdThe ID of the channel.[a-f 0-9]32Required for Option 4
webhookIdThe ID of the webhook.[a-f 0-9]32Required

Data parameters

No parameters required.

Success response

200: OKThe request was successful.

Response is a validation object with the following structure:

bodyThe response body.--
headerThe response headers.--
statusCodeThe HTTP response status code.--

If the statusCode is successful (2xx), the webhook is marked as confirmed.

Response Example

Error response

200.*.*Used to tunnel errors. Check the error message.

Example

GET/psps/{pspId}/webhooks/{webhookId}/validate
GET/divisions/{divisionsId}/webhooks/{webhookid}/validate
GET/merchants/{merchantId}/webhooks/{webhookId}/validate
GET/channels/{channelId}/webhooks/{webhookId}/validate

Request sample

curl -X GET \
  'https://eu-test.oppwa.com/bip/webapi/v1/channels/{channelId}/webhooks/{webhookId}/validate' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>'

Response samples

{
  "validation": {
    "body": "This URL has no default content configured.",
    "headers": {
      "transfer-encoding": "chunked",
      "x-token-id": "7854d338-b0c1-4533-aed2-5b42f979664b",
      "server": "nginx",
      "cache-control": "no-cache, private",
      "content-type": "text/html; charset=UTF-8",
      "x-request-id": "f8069f1d-06fa-405b-b265-fe318919eb0d",
      "date": "Wed, 21 Oct 2026 08:51:41 GMT",
      "content-security-policy": "base-uri 'self'; form-action 'none'; script-src 'none'; worker-src 'none'; frame-src 'none';"
    },
    "statusCode": 200
  }
}

Update Webhook State

The call activates or deactivates the webhook. In case of activation, a test webhook request is sent (the same action as Validate Webhook). If the request is successful (2xx), the webhook becomes active.

The webhook state can be updated at PSP, division, merchant, or channel levels.

Endpoints

POST/psps/{pspId}/webhooks/{webhookId}/state
Option 1. Update webhook state using PSP ID and webhook ID.
POST/divisions/{divisionsId}/webhooks/{webhookid}/state
Option 2. Update webhook state using division ID and webhook ID.
POST/merchants/{merchantId}/webhooks/{webhookId}/state
Option 3. Update webhook state using merchant ID and webhook ID.
POST/channels/{channelId}/webhooks/{webhookId}/state
Option 4. Update webhook state using channel ID and webhook ID.

URL parameters

pspIdrequired for option 1
[a-f 0-9]32
The ID of the PSP.
divisionIdrequired for option 2
[a-f 0-9]32
The ID of the division.
merchantIdrequired for option 3
[a-f 0-9]32
The ID of the merchant.
channelIdrequired for option 4
[a-f 0-9]32
The ID of the channel.
webhookIdrequired
[a-f 0-9]32
The ID of the webhook.

Data parameters

No parameters required.

Success response

200: OKThe request was successful.

Response is a validation object with the following structure:

body
The response body.
header
The response headers.
statusCode
The HTTP response status code.

If the statusCode is successful (2xx), the webhook is marked as confirmed and active.

Error response

200.*.*Used to tunnel errors. Check the error message.
POST/psps/{pspId}/webhooks/{webhookId}/state
POST/divisions/{divisionsId}/webhooks/{webhookid}/state
POST/merchants/{merchantId}/webhooks/{webhookId}/state
POST/channels/{channelId}/webhooks/{webhookId}/state

Request sample

curl -X POST \
  'https://eu-test.oppwa.com/bip/webapi/v1/channels/{channelId}/webhooks/{webhookId}/state' \
  -H 'accept: application/json' \
  -H 'credentials: <username>:<password>' \
  -H 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8' \
  --data-urlencode 'active=true'

Response samples

{
  "validation": {
    "body": "This URL has no default content configured. <a href=\"https://webhook.site/#!/edit/7854d338-b0c1-4533-aed2-5b42f979664b\">Change response in Webhook.site</a>.",
    "headers": {
      "transfer-encoding": "chunked",
      "x-token-id": "7854d338-b0c1-4533-aed2-5b42f979664b",
      "server": "nginx",
      "cache-control": "no-cache, private",
      "content-type": "text/html; charset=UTF-8",
      "x-request-id": "e416c6ab-5ea8-456f-b5da-3f97acbc6cca",
      "date": "Wed, 21 Oct 2026 08:52:04 GMT",
      "content-security-policy": "signup-to-remove-csp-header 'webhook.site/register'; base-uri 'self'; form-action 'none'; script-src 'none'; worker-src 'none'; frame-src 'none';"
    },
    "statusCode": 200
  }
}