Merchant Onboarding API

Last updated: November 5, 2026

Contact operations

Review point

Path parameters are written inconsistently in the Confluence pages ({pspid}, {divisionsid}, {contactid} vs pspId… in the parameter tables); kept as in the source.

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 contactusing merchant ID.

POST/merchants/{channelid}/ownedContacts

Option 4. Add a contactusing 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

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.

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

POST/merchants/{channelid}/ownedContacts

Request sample

curl -X POST \
  'https://eu-test.oppwa.com/bip/webapi/v1/psps/{pspId}/ownedContacts' \
  -H 'credentials: <username>:<password>' \
  -F 'email=test@example.com' \
  -F 'name=Test Account' \
  -F 'role=CALLCENTER' \
  -F 'kind=SEND' \
  -F '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.

Review point

Data parameters read “(no parameter allowed)”; the success example was not valid JSON (repaired).

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 'credentials: <username>:<password>'

Response samples

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

{
  "error": {
    "message": "Invalid contact id or missing configuration."
  }
}

Get Contact

The call gets information about an existing contact.

Review point

The example shows role as “Operator” but the documented values are upper case; username appears in the example but not in the field table.

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.

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 '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"
  }
}

{
  "error": {
    "message": "Invalid contact id or missing configuration."
  }
}

Edit Contact

The call edits an existing contact.

Review points

The “Required” column has no header; language is marked Required although omitted parameters stay unchanged; the example response has no language.
The Confluence sample used a legacy payon.com address (replaced by example.com).

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.

languagerequired

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.

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 'credentials: <username>:<password>' \
  -F 'email=test@example.com' \
  -F 'name=New Name' \
  -F 'role=ANALYSIS' \
  -F 'kind=SEND' \
  -F 'language=en'

Response samples

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

{
  "error": {
    "message": "Invalid contact id or missing configuration."
  }
}

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.

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 '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"
  }
}

{
  "error": {
    "message": "Invalid contact id or missing configuration."
  }
}

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.

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 '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"
  }
}

{
  "error": {
    "message": "Invalid contact id or missing configuration."
  }
}

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 'credentials: <username>:<password>'

Response samples

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

{
  "error": {
    "message": "Invalid contact id or missing configuration."
  }
}

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.

Review point

Confluence note (2016-10-06): the call worked only for attaching contacts at the same hierarchy level that owns the contact. Still true?

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.

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.

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 '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"
  }
}

{
  "error": {
    "code": "200.300.406",
    "message": "Unable to find entity (e.g. division, merchant, or channel) with id : ab12cd34ef56ab12cd34ef56ab12cd04"
  }
}

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 'credentials: <username>:<password>'

Response samples

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

{
  "error": {
    "message": "Contact doesn't exist."
  }
}

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.

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 '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"
    }
  ]
}

{
  "error": {
    "code": "200.300.406",
    "message": "Unable to find entity (e.g. division, merchant, or channel) with id : ab12cd34ef56ab12cd34ef56ab12cd04"
  }
}

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.

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 '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"
    }
  ]
}

{
  "error": {
    "code": "200.300.406",
    "message": "Unable to find entity (e.g. division, merchant, or channel) with id : ab12cd34ef56ab12cd34ef56ab12cd04"
  }
}

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.

Review point

The error example is not valid JSON in the source and is shown as it is.

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 'credentials: <username>:<password>'

Response samples

{
  "clearingInstitutes": []
}

{
  "clearingInstitutes": [
    {
      "country": "DE",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd07",
      "internationalCode": " ",
      "name": "Acceptance Test"
    },
    {
      "country": "NL",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd08",
      "internationalCode": " ",
      "name": "Afterpay"
    },
    {
      "country": "CN",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd09",
      "name": "Alipay"
    },
    {
      "country": "DE",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd10",
      "internationalCode": " ",
      "name": "Amex Test"
    },
    {
      "country": "BR",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd11",
      "internationalCode": " ",
      "name": "AstroPay CI"
    },
    {
      "country": "BR",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd12",
      "internationalCode": " ",
      "name": "AstroPay Streamline CI"
    },
    {
      "country": "ES",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd13",
      "internationalCode": " ",
      "name": "BANC SABADELL CI"
    },
    {
      "country": "BR",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd14",
      "name": "BRADESCO_TEST"
    },
    {
      "country": "LI",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd15",
      "internationalCode": " ",
      "name": "BankFrick"
    },
    {
      "country": "UK",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd16",
      "internationalCode": " ",
      "name": "Bitnet Demo"
    },
    {
      "country": "CN",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd17",
      "internationalCode": " ",
      "name": "CHINAPAY"
    },
    {
      "country": "ES",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd18",
      "internationalCode": " ",
      "name": "CIELO"
    },
    {
      "country": "AE",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd19",
      "internationalCode": " ",
      "name": "CashU Test"
    },
    {
      "country": "DE",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd20",
      "internationalCode": " ",
      "name": "Certification"
    },
    {
      "country": "US",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd21",
      "internationalCode": " ",
      "name": "Chase_Orbital"
    },
    {
      "country": "US",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd22",
      "internationalCode": " ",
      "name": "Chase_Stratus"
    },
    {
      "country": "UK",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd23",
      "internationalCode": " ",
      "name": "CredoraxOmnipayDemoTest"
    },
    {
      "country": "AT",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd24",
      "internationalCode": " ",
      "name": "DaoPay Test"
    },
    {
      "country": "AT",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd25",
      "name": "EPSSO_CI"
    },
    {
      "country": "MT",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd26",
      "name": "Entercash Test"
    },
    {
      "country": "UK",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd27",
      "internationalCode": " ",
      "name": "FDMS_UK"
    },
    {
      "country": "DE",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd28",
      "name": "Giropay Fiducia"
    },
    {
      "country": "TR",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd29",
      "internationalCode": " ",
      "name": "Iyzico Akbank Demo"
    },
    {
      "country": "TR",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd30",
      "internationalCode": " ",
      "name": "Iyzico Bankasya Demo"
    },
    {
      "country": "TR",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd31",
      "internationalCode": " ",
      "name": "Iyzico Denizbank Demo"
    },
    {
      "country": "TR",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd32",
      "internationalCode": " ",
      "name": "Iyzico Finansbank Demo"
    },
    {
      "country": "TR",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd33",
      "internationalCode": " ",
      "name": "Iyzico Isbank Demo"
    },
    {
      "country": "TR",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd34",
      "internationalCode": " ",
      "name": "Iyzico Yapikredi Demo"
    },
    {
      "country": "TR",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd35",
      "internationalCode": " ",
      "name": "Iyzico iPara Demo"
    },
    {
      "country": "DE",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd36",
      "internationalCode": " ",
      "name": "Klarna Checkout"
    },
    {
      "country": "SE",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd37",
      "internationalCode": " ",
      "name": "Klarna Test"
    },
    {
      "country": "US",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd38",
      "internationalCode": " ",
      "name": "MasterPass test"
    },
    {
      "country": "CA",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd39",
      "name": "Moneris Onlinetransfer"
    },
    {
      "country": "DE",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd40",
      "internationalCode": " ",
      "name": "MoneyBookers Test",
      "nationalCode": " "
    },
    {
      "country": "CY",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd41",
      "name": "Moneysafe"
    },
    {
      "country": "UK",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd42",
      "internationalCode": " ",
      "name": "Neteller Demo"
    },
    {
      "country": "SA",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd43",
      "internationalCode": " ",
      "name": "ONECARD"
    },
    {
      "country": "AU",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd44",
      "name": "POLi test"
    },
    {
      "country": "CH",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd45",
      "name": "POSTFINANCE_EPAY CI"
    },
    {
      "country": "DE",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd46",
      "internationalCode": " ",
      "name": "PayPal Test"
    },
    {
      "country": "DE",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd47",
      "internationalCode": " ",
      "name": "PayTrail test"
    },
    {
      "country": "AT",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd48",
      "name": "Paybox"
    },
    {
      "country": "DE",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd49",
      "internationalCode": " ",
      "name": "Paydirekt demo CI"
    },
    {
      "country": "DE",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd50",
      "name": "Payolution Test"
    },
    {
      "country": "AT",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd51",
      "internationalCode": " ",
      "name": "Paysafecard PSC"
    },
    {
      "country": "ES",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd52",
      "internationalCode": " ",
      "name": "Payvision V2"
    },
    {
      "country": "DE",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd53",
      "internationalCode": " ",
      "name": "Postbank ELV SEPA",
      "nationalCode": " "
    },
    {
      "country": "CH",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd54",
      "name": "Postfinance Demo CI"
    },
    {
      "country": "PL",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd55",
      "name": "Przelewy Test"
    },
    {
      "country": "RU",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd56",
      "internationalCode": " ",
      "name": "Qiwi Test"
    },
    {
      "country": "DE",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd57",
      "internationalCode": " ",
      "name": "SOFORT-Banking_Test"
    },
    {
      "country": "IR",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd58",
      "internationalCode": " ",
      "name": "Shetab Primeiropay Demo"
    },
    {
      "country": "DE",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd59",
      "name": "Starfinanz GIROPAY_SEPA"
    },
    {
      "country": "SK",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd60",
      "internationalCode": " ",
      "name": "TRUSTPAY_VA"
    },
    {
      "country": "CN",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd61",
      "internationalCode": " ",
      "name": "TenPay"
    },
    {
      "country": "DE",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd62",
      "internationalCode": " ",
      "name": "Trustly Demo"
    },
    {
      "country": "GB",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd63",
      "name": "UKASH Demo"
    },
    {
      "country": "RU",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd64",
      "name": "YANDEX_Test"
    },
    {
      "country": "BR",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd65",
      "name": "allpago Alternatives"
    },
    {
      "country": "NL",
      "id": "ab12cd34ef56ab12cd34ef56ab12cd66",
      "name": "iDeal_ING_SEPA"
    }
  ]
}

<html></html>

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.

Review points

state is marked Required, but its description says the default is inherited from the parent entity.
description: 32 characters in the request, 50 in the response.

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], [-_ ]32

A description of the entity.

staterequired

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 'credentials: <username>:<password>' \
  -F 'name=New Test Division' \
  -F 'state=INTEGRATOR_TEST' \
  -F 'description=For testing purposes'

Response samples

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

{
  "error": {
    "code": "200.300.404",
    "message": "Error - POST parameter validation failure(s). 'description' is only allowed to contain the characters [A-Za-z0-9_- ]."
  }
}

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 'credentials: <username>:<password>'

Response samples

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

{
  "error": {
    "code": "200.300.406",
    "message": "Unable to find entity (e.g. division, merchant, or channel) with id : ab12cd34ef56ab12cd34ef56ab12cd69"
  }
}

Edit Division

The call allows editing the information for an existing division.

Review point

Success code reads “201:Created” for an update; name reads “to be created”.

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 to be created.

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

The default value is inherited from the parent entity. Possible values are “LIVE”, “CONNECTOR_TEST”, “INTEGRATOR_TEST”, or “DISABLED”

Success response

201:CreatedThe 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 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 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 'credentials: <username>:<password>' \
  -F 'name=New Name' \
  -F 'state=DISABLED' \
  -F 'description=Updated description'

Response samples

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

{
  "error": {
    "code": "200.300.404",
    "message": "Error - POST parameter validation failure(s). 'name' must be between 1 and 100 characters long."
  }
}

Get Divisions List

The call lists the information about existing divisions.

Review point

The Confluence example contained placeholder values ("description": "A", "customerId": "id").

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 '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"
    }
  ]
}

{
  "error": {
    "code": "200.300.406",
    "message": "Unable to find entity (e.g. division, merchant, or channel) with id : ab12cd34ef56ab12cd34ef56ab12cd04"
  }
}

Delete Division

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

Review point

Confluence note (2016-09-13): “The call did not work.” The success code is empty and the page has no response example. Does the call work today?

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

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 '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.

Review points

state is marked Required, but its description says the default value is inherited from the parent entity.
id in the response is described as “The name of the merchant to be created”; response name allows 256 characters, the request 32. [A-Z a-z 0-9] appears to allow spaces, while the Merchant Portal walkthrough says to avoid them.
secret is returned but documented as Legacy, not used anymore.

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], [-_]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 integrate.

descriptionOptional

[A-Z a-z 0-9], [-_ ]50

A simple description of the entity.

staterequired

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 name of the merchant to be created.

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 'credentials: <username>:<password>' \
  -F 'name=New Test Merchant' \
  -F 'state=INTEGRATOR_TEST' \
  -F '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"
  }
}

{
  "error": {
    "code": "200.300.404",
    "message": "Error - POST parameter validation failure(s). 'state' is invalid. Only these, case-insensitive, options are allowed: disabled, live, integrator_test, connector_test."
  }
}

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 'credentials: <username>:<password>'

Response samples

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

{
  "error": {
    "code": "200.300.406",
    "message": "Unable to find entity (e.g. division, merchant, or channel) with id : ab12cd34ef56ab12cd34ef56ab12cd73"
  }
}

Edit Merchant

The call edits the information for an existing merchant.

Review point

Success code reads “201: Created” for an update; description length 32 in the request vs 50 in the response.

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 to be created.

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], [-_ ]32

A simple description of the entity.

staterequired

The default value is inherited from the parent entity. Possible values are “LIVE”, “CONNECTOR_TEST”, “INTEGRATOR_TEST”, or “DISABLED”.

Success response

201: CreatedThe 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 'credentials: <username>:<password>' \
  -F 'name=New Merchant Name' \
  -F 'state=INTEGRATOR_TEST' \
  -F '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"
  }
}

{
  "error": {
    "code": "200.300.404",
    "message": "Error - POST parameter validation failure(s). 'description' is only allowed to contain the characters [A-Za-z0-9_- ]."
  }
}

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 '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"
    }
  ]
}

{
  "error": {
    "code": "200.300.406",
    "message": "Unable to find entity (e.g. division, merchant, or channel) with id : ab12cd34ef56ab12cd34ef56ab12cd68"
  }
}

Delete Merchant

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

Review point

Soft delete (state set to DISABLED); returns merchantInfo – response shape differs from the other delete calls.

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 'credentials: <username>:<password>'

Response samples

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

{
  "error": {
    "code": "200.300.406",
    "message": "Unable to find entity (e.g. division, merchant, or channel) with id : ab12cd34ef56ab12cd34ef56ab12cd77"
  }
}

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.

Review points

URL parameter name reads “The entity name identifying the merchant”; Option 2 reads “Add a merchant using entity path”; response id reads “The name of the channel to be created”.
state is marked Required, but its description says the default is inherited.

Endpoints

POST/merchants/{merchantId}/channels

Option 1. Add a channel using merchant ID.

POST/entities/byName/{pspName}/{divisionName}/{name}/channels

Option 2. Add a merchant 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 merchant.

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

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 name of the channel to be created.

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 'credentials: <username>:<password>' \
  -F 'name=Test Channel Name' \
  -F 'state=INTEGRATOR_TEST' \
  -F '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"
}

{
  "error": {
    "code": "200.300.404",
    "message": "Error - POST parameter validation failure(s). 'name' is required."
  }
}

Get Channel

The call gets information about an existing channel.

Review point

id reads “The name of the channel to be created”.

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 name of the channel to be created.

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 '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"
  }
}

{
  "error": {
    "code": "200.300.406",
    "message": "Unable to find entity (e.g. division, merchant, or channel) with id : ab12cd34ef56ab12cd34ef56ab12cd80"
  }
}

Edit Channel

The call edits the information for an existing channel.

Review point

Success code reads “201: Created” for an update; id reads “The name of the channel to be created”.

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

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 at a later point in time to simply integration.

descriptionOptional

[A-Z a-z 0-9], [-_ ]50

A simple description of the entity.

staterequired

The default value is inherited from the parent entity. Possible values are “LIVE”, “CONNECTOR_TEST”, “INTEGRATOR_TEST”, or “DISABLED”.

Success response

201: CreatedThe details of the channel were updated successfully.

id

[a-f 0-9]32

The name of the channel to be created.

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 'credentials: <username>:<password>' \
  -F 'name=New Channel Name' \
  -F 'state=INTEGRATOR_TEST' \
  -F '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"
}

{
  "error": {
    "code": "200.300.404",
    "message": "Error - POST parameter validation failure(s). 'name' must be between 1 and 100 characters long."
  }
}

Get Channels List

The call allows listing information about existing channels.

Review point

The URL text reads “List the merchants using merchantID”; merchantId is “Required for Option 1” but there is only one option; id reads “The name of the channel to be created”.

Endpoints

GET/merchants/{merchantId}/channels

List the merchants using merchantID.

URL parameters

merchantIdrequired for option 1

[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 name of the channel to be created.

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 '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"
    }
  ]
}

{
  "error": {
    "code": "999.999.999",
    "message": "Error - Internal error"
  }
}

Delete Channel

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

Review point

Soft delete (state set to DISABLED); returns channelInfo without a field table – the response shape differs from Delete Merchant / Merchant Account.

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.

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 '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"
  }
}

{
  "error": {
    "code": "200.300.406",
    "message": "Unable to find entity (e.g. division, merchant, or channel) with id : ab12cd34ef56ab12cd34ef56ab12cd85"
  }
}

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.<parameter>

[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-f 0-9]32

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.<parameter>

[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 'credentials: <username>:<password>' \
  -F 'name=Test merchant account' \
  -F 'state=TEST' \
  -F 'clearingInstituteId=ff8081816030b48a016030b49a6c0014' \
  -F 'iban=TT1234TTT00000000' \
  -F 'username=testusername' \
  -F 'password=testpassword' \
  -F 'merchantCategory=RETAIL' \
  -F 'transactionCategory=ECOMMERCE' \
  -F 'avsCheckActive=TRUE' \
  -F 'avsRejectionPolicy=A' \
  -F 'avsReviewPolicy=A' \
  -F 'debitAdviceProcedure=DD' \
  -F 'recurringCode=NONE' \
  -F 'supports3DSecure=TRUE' \
  -F 'merchant3DName=test' \
  -F 'merchant3DUrl=https://test.com/3d' \
  -F 'merchantIsoCountryCode=630' \
  -F 'bankfileGenerationPattern=DAILY@5:00 UTC' \
  -F 'velocityDispachingActive=TRUE' \
  -F 'velocityDispatchingSetting=12;11;2;DAY' \
  -F 'ticketSizeDispatchingActive=TRUE' \
  -F 'ticketSizeDispatchingSetting=2;10' \
  -F 'recurringDispatchingSetting=ALL' \
  -F 'shopperDispatchingSetting=ALL' \
  -F 'shopperDispatchingScope=PSP' \
  -F 'shopperDispatchingValidity=10' \
  -F 'paymentDispatchingSetting=CREDITS' \
  -F 'uploadUser=uploadUsername' \
  -F 'uploadPassword=uploadPass' \
  -F 'connectorSpecificParameter.AD_SUB_MERCHANT_CITY=subMerchantCity' \
  -F 'connectorSpecificParameter.AD_SUB_MERCHANT_EMAIL=subMerchantEmail' \
  -F '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"
  }
}

{
  "error": {
    "code": "200.300.404",
    "message": "Error - POST parameter validation failure(s). either a clearingInstituteId or a clearingInstituteName is necessary."
  }
}

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-f 0-9]32

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.<parameter>

[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 '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"
  }
}

{
  "error": {
    "code": "200.300.406",
    "message": "Unable to find merchant account with id : ab12cd34ef56ab12cd34ef56ab12cd87"
  }
}

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.<parameter>

[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-f 0-9]32

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.<parameter>

[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 'credentials: <username>:<password>' \
  -F 'name=Test merchant account' \
  -F 'state=TEST' \
  -F 'clearingInstituteId=ff8081816030b48a016030b49a6c0014' \
  -F 'iban=TT1234TTT00000000' \
  -F 'username=testusername' \
  -F 'password=testpassword' \
  -F 'merchantCategory=RETAIL' \
  -F 'transactionCategory=ECOMMERCE' \
  -F 'avsCheckActive=TRUE' \
  -F 'avsRejectionPolicy=A' \
  -F 'avsReviewPolicy=A' \
  -F 'debitAdviceProcedure=DD' \
  -F 'recurringCode=NONE' \
  -F 'supports3DSecure=TRUE' \
  -F 'merchant3DName=test' \
  -F 'merchant3DUrl=https://test.com/3d' \
  -F 'merchantIsoCountryCode=630' \
  -F 'bankfileGenerationPattern=DAILY@5:00 UTC' \
  -F 'velocityDispachingActive=TRUE' \
  -F 'velocityDispatchingSetting=12;11;2;DAY' \
  -F 'ticketSizeDispatchingActive=TRUE' \
  -F 'ticketSizeDispatchingSetting=2;10' \
  -F 'recurringDispatchingSetting=ALL' \
  -F 'shopperDispatchingSetting=ALL' \
  -F 'shopperDispatchingScope=PSP' \
  -F 'shopperDispatchingValidity=10' \
  -F 'paymentDispatchingSetting=CREDITS' \
  -F 'uploadUser=uploadUsername' \
  -F 'uploadPassword=uploadPass' \
  -F 'connectorSpecificParameter.AD_SUB_MERCHANT_CITY=subMerchantCity' \
  -F 'connectorSpecificParameter.AD_SUB_MERCHANT_EMAIL=subMerchantEmail' \
  -F '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"
  }
}

{
  "error": {
    "code": "200.300.406",
    "message": "Unable to find merchant account with id : ab12cd34ef56ab12cd34ef56ab12cd87"
  }
}

Delete Merchant Account

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

Review point

Soft delete (state set to DISABLED); returns an empty body – response shape differs from the other delete calls.

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 'credentials: <username>:<password>'

Response samples

{}

{
  "error": {
    "code": "200.300.406",
    "message": "Unable to find merchant account with id : ab12cd34ef56ab12cd34ef56ab12cd88"
  }
}

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

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]

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-f 0-9]32

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 'credentials: <username>:<password>' \
  -F 'merchantAccountId=ff8081816953558101695716b6c70014' \
  -F 'fallbackMerchantAccountId=ff8081817ad3d41d017ad3d45370010a' \
  -F 'currency=EUR' \
  -F 'binCountryLimit=DE;RO;US' \
  -F 'binRangeLimit=000000:999999' \
  -F 'processTransactionsWithoutBinIdentification=true' \
  -F 'subTypes=VISA' \
  -F 'clearingInstituteId=ff8081816030b48a016030b49a6c0014' \
  -F 'customDescriptor1=AAA' \
  -F 'customDescriptor2=BBB' \
  -F 'customDescriptor3=CCC' \
  -F 'selectionDescriptor1=CHANNEL_NAME' \
  -F 'selectionDescriptor2=INVOICE_ID' \
  -F 'selectionDescriptor3=TRANSACTION_ID'

Response samples

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

{
  "error": {
    "code": "200.300.404",
    "message": "Error - POST parameter validation failure(s). 'subTypes' is required."
  }
}

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

customDescriptor1 customDescriptor2 customDescriptor3Optional

[A-Z a-z 0-9], [-_ ]

selectionDescriptor1 selectionDescriptor2 selectionDescriptor3Optional

[A-Z a-z 0-9], [-_ ]

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-f 0-9]32

descriptor

[A-Z a-z 0-9], [-_ ]255

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 'credentials: <username>:<password>' \
  -F 'merchantAccountId=ff8081816953558101695716b6c70014' \
  -F 'fallbackMerchantAccountId=ff8081817ad3d41d017ad3d45370010a' \
  -F 'currency=EUR' \
  -F 'binCountryLimit=DE;RO;US' \
  -F 'binRangeLimit=000000:999999' \
  -F 'processTransactionsWithoutBinIdentification=true' \
  -F 'subTypes=VISA' \
  -F 'clearingInstituteId=ff8081816030b48a016030b49a6c0014' \
  -F 'customDescriptor1=AAA' \
  -F 'customDescriptor2=BBB' \
  -F 'customDescriptor3=CCC' \
  -F 'selectionDescriptor1=CHANNEL_NAME' \
  -F 'selectionDescriptor2=INVOICE_ID' \
  -F '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": ""
  }
}

{
  "error": {
    "code": "200.300.406",
    "message": "Unable to find attached merchant account with id : ab12cd34ef56ab12cd34ef56ab12cd90"
  }
}

Detach Merchant Account

The call detaches an attached merchant account.

Review point

The success code is empty and the example is { }.

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

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 '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.

Review point

Confluence note (2016-11-24): the call did not work at Division level. Still true?

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-f 0-9]32

descriptor

[A-Z a-z 0-9], [-_ ]255

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 '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"
    }
  ]
}

{
  "error": {
    "code": "200.300.406",
    "message": "Unable to find entity (e.g. division, merchant, or channel) with id : ab12cd34ef56ab12cd34ef56ab12cd95"
  }
}

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-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.

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 '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"
    }
  ]
}

{
  "error": {
    "code": "200.300.406",
    "message": "Unable to find entity (e.g. division, merchant, or channel) with id : ab12cd34ef56ab12cd34ef56ab12cd04"
  }
}

3D Secure setup

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

Review points

Confluence note (2016-11-08): the calls are yet to be verified and the page is to be filled with the remaining missing information.
The Confluence page showed a second sample call (legacy host and personal credentials); it was removed.
A response example could not be repaired into valid JSON and is shown as in the source.
The error example is not valid JSON in the source and is shown as it is.

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 'credentials: <username>:<password>' \
  -F 'supports3DSecure=TRUE' \
  -F 'merchant3DName=Merchant 3D name' \
  -F 'merchant3DUrl=https://test.com/3d' \
  -F 'merchantIsoCountryCode=630' \
  -F 'visaMerchantId=12345' \
  -F 'visaMerchantAcquirerBin=4200' \
  -F 'masterMerchantId=654321' \
  -F 'masterMerchantAcquirerBin=5200'

Response samples

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

{
 to be added
}

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.

Review points

Confluence note (2016-11-08): the call is yet to be verified and the page is to be filled with the remaining missing information. The Sample call is empty; the URL text reads “Check the enrollment status”.
A response example could not be repaired into valid JSON and is shown as in the source.

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

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.

Detach All Attached Merchant Accounts

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

Review points

The success code reads “N/A”; destructive call.
The Confluence page showed a second sample call (legacy host and personal credentials); it was removed.

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

N/A

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 'credentials: <username>:<password>'

Response samples

{}

{
  "error": {
    "message": "Unauthorized - Invalid credentials"
  }
}

Delete All Owned Merchant Accounts

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

Review points

Typo in Option 4 (“Delete allowned…”); the sample link text and URL disagreed (attached vs owned); destructive call.
The Confluence page showed a second sample call (legacy host and personal credentials); it was removed.

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 allowned 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 'credentials: <username>:<password>'

Response samples

{}

{
  "error": {
    "code": "999.999.999",
    "message": "Merchant account still has usages. Unable to delete merchant account with id : ab12cd34ef56ab12cd34ef56ab12cd97"
  }
}

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.

Review point

To verify with the SME: the overview lists PSP and Division paths as supported, while this page says they are “not supported” (probably forgotten in an update). The URL parameters table lists all four IDs as Required; the sample used DD:active, the response example CC:active.

Endpoints

GETpsps/{pspid}/setting- not supported

View the value of a RiRo setting using the ID of the entity:

GETdivisions/{divisionsid}/setting- not supported

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 'credentials: <username>:<password>'

Response samples

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

{
  "error": {
    "code": "200.300.404",
    "message": "Parameter 'key' not valid or missing."
  },
  "key": ""
}

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.

Review point

This call lists all four levels as supported, unlike Get RiRo setting value. The “Keys for configuring RiRo settings” link pointed to another Confluence space (/display/IO/).

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 'credentials: <username>:<password>' \
  -F 'key=*/type:entity/module:frontend/processing:frontend/frontend:DD/DD:active' \
  -F 'value=false'

Response samples

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

{
  "error": {
    "code": "200.300.404",
    "message": "Parameter 'value' not valid. It must be either 'true' or 'false', case-insensitive."
  },
  "key": "*/type:entity/module:frontend/processing:frontend/frontend:CC/CC:active",
  "value": "disabled"
}

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.

Review points

Option 1 text reads “List the api tokensusing merchant id”; the Confluence example lacked its opening brace (repaired).
The Confluence sample used -X POST; corrected to -X GET to match the operation.

Endpoints

GETmerchants/{merchantId}/apiTokens

Option 1. List the api tokensusing merchant id.

URL parameters

merchantIdrequired for option 1

[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 '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"
    }
  ]
}

{
  "result": {
    "code": "200.300.406",
    "description": "Page not found",
    "timestamp": "2026-03-09 13:54:39"
  },
  "buildNumber": "20141216-153400.r1.static",
  "ndc": "4s5fktukd7scerjk3zgowtbjtqo3ssxf"
}

Get API Token

The call povides the information the API Token specified by id

Review point

Option 1 text reads “List the api tokensusing merchant id” for a get-by-ID call; typo “povides”.

Endpoints

GET/apiTokens/{apiTokenId}

Option 1. List the api tokensusing merchant id.

URL parameters

apiTokenIdrequired for option 1

[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 '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"
  }
}

{
  "result": {
    "code": "200.300.406",
    "description": "Page not found",
    "timestamp": "2026-03-09 13:54:39"
  },
  "buildNumber": "20141216-153400.r1.static",
  "ndc": "4s5fktukd7scerjk3zgowtbjtqo3ssxf"
}

Create API Token for Merchant

The call adds a new api token for a merchant

Review point

Option 1 text reads “Add a channel using merchant ID”; the error example is a copy of the channel example (“‘name’ is required”) although the call has no body.

Endpoints

POST/merchants/{merchantId}/apiTokens

Option 1. Add a channel using merchant ID.

URL parameters

merchantIdrequired for option 1

[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 '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"
  }
}

{
  "error": {
    "code": "200.300.404",
    "message": "Error - POST parameter validation failure(s). 'name' is required."
  }
}

Suspend API Token

The call suspend an api token

Review point

apiTokenId is “Required for Option 1” but there is only one URL.

Endpoints

POSTapiTokens/{apiTokenId}/suspend

URL parameters

apiTokenIdrequired for option 1

[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 '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"
  }
}

{
  "error": {
    "code": "200.300.404",
    "message": "Error - POST parameter validation failure(s). 'name' is required."
  }
}

Activate API Token

The call to activate an API token

Review point

apiTokenId is “Required for Option 1” but there is only one URL; the sample link text and target disagreed (activate vs suspend).

Endpoints

POSTapiTokens/{apiTokenId}/activate

URL parameters

apiTokenIdrequired for option 1

[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 '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"
  }
}

{
  "error": {
    "code": "200.300.404",
    "message": "Error - POST parameter validation failure(s). 'name' is required."
  }
}

Update API Token

The call to update an api token

Review point

Success description reads “Token was suspended”; the example shows state ACTIVE while the table says SUSPENDED.

Endpoints

POSTapiTokens/{apiTokenId}

URL parameters

apiTokenIdrequired for option 1

[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 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}

Request sample

curl -X POST \
  'https://eu-test.oppwa.com/bip/webapi/v1/apiTokens/{apiTokenId}' \
  -H 'credentials: <username>:<password>' \
  -F '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"
  }
}

{
  "error": {
    "code": "200.300.404",
    "message": "Error - POST parameter validation failure(s). 'name' is required."
  }
}

Delete API Token

The call to delete an api token

Review point

Success description reads “Token was suspended”; the error example says only suspended tokens can be deleted.

Endpoints

DELETEapiTokens/{apiTokenId}

URL parameters

apiTokenIdrequired for option 1

[a-f 0-9]32

The ID of the API token.

Success response

200: SuccessToken was suspended

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 '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.

Review point

The Method value is missing in the Confluence export; POST taken from the Webhook operations overview.

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 'credentials: <username>:<password>' \
  -F 'endpoint=https://example.com' \
  -F 'notificationTypes.payments=PA,CP,DB' \
  -F 'notificationTypes.registrations=ALL' \
  -F 'preset=ALL' \
  -F '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"
  }
}

{
  "error": {
    "code": "200.300.404",
    "message": "secret ('foo'): must match [0-9a-fA-F]{64}"
  }
}

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


pspId	The ID of the PSP.	[a-f 0-9]	32	Required for Option 1
divisionId	The ID of the division.	[a-f 0-9]	32	Required for Option 2
merchantId	The ID of the merchant.	[a-f 0-9]	32	Required for Option 3
channelId	The ID of the channel.	[a-f 0-9]	32	Required for Option 4


webhookId	The ID of the webhook.	[a-f 0-9]	32	Required

Data parameters

No parameters required.

Success response


200: OK	The request was successful.

Response is a webhook object with the following structure:


id	The webhook ID.	[a-f 0-9]	32
entityId	The entity (PSP, division, merchant, or channel) ID, where the webhook is attached to.	[a-f 0-9]	32
confirmed	The flag indicating whether the webhook is validated.	false/true	-
active	The flag indicating whether the webhook is active.	false/true	-
endpoint	The 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	-	-
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	A 64-character hex string used to encrypt the payload.	[0-9 a-f A-F]	64
emails	Array 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 '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"
  }
}

{
  "error": {
    "code": "200.300.406",
    "message": "Webhook not found: ab12cd34ef56ab12cd34ef56ab12cd106"
  }
}

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


pspId	The ID of the PSP.	[a-f 0-9]	32	Required for Option 1
divisionId	The ID of the division.	[a-f 0-9]	32	Required for Option 2
merchantId	The ID of the merchant.	[a-f 0-9]	32	Required for Option 3
channelId	The ID of the channel.	[a-f 0-9]	32	Required for Option 4


webhookId	The ID of the webhook.	[a-f 0-9]	32	Required

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.


endpoint	The 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.	-	-
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	A 64-character hex string used to encrypt the payload. If empty, a random secret is generated.	[0-9 a-f A-F]	64
emails	One or more email addresses to receive daily failure summaries. Use commas to separate email addresses.	-	-

Success response


200: OK	The request was successful.

Response is a webhook object with the following structure:


id	The webhook ID.	[a-f 0-9]	32
entityId	The entity (PSP, division, merchant, or channel) ID, where the webhook is attached to.	[a-f 0-9]	32
confirmed	The flag indicating whether the webhook is validated.	false/true	-
active	The flag indicating whether the webhook is active.	false/true	-
endpoint	The 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	-	-
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	A 64-character hex string used to encrypt the payload.	[0-9 a-f A-F]	64
emails	Array 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 'credentials: <username>:<password>' \
  -F 'notificationTypes.payments=PA,DB' \
  -F 'notificationTypes.registrations=' \
  -F 'preset=NON_CUSTOMER_DATA' \
  -F '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"
  }
}

{
  "error": {
    "code": "200.300.404",
    "message": "Parameter 'notificationTypes.payments': 'ALL' cannot be combined with other notification types."
  }
}

List Webhooks

The call allows listing information about existing webhooks.

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

Review point

The Error response is empty in the source.

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


pspId	The ID of the PSP.	[a-f 0-9]	32	Required for Option 1
divisionId	The ID of the division.	[a-f 0-9]	32	Required for Option 2
merchantId	The ID of the merchant.	[a-f 0-9]	32	Required for Option 3
channelId	The ID of the channel.	[a-f 0-9]	32	Required for Option 4

Data parameters

No parameters required.

Success response


200: OK	The request was successful.

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


id	The webhook ID.	[a-f 0-9]	32
entityId	The entity (PSP, division, merchant, or channel) ID, where the webhook is attached to.	[a-f 0-9]	32
confirmed	The flag indicating whether the webhook is validated.	false/true	-
active	The flag indicating whether the webhook is active.	false/true	-
endpoint	The 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	-	-
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	A 64-character hex string used to encrypt the payload.	[0-9 a-f A-F]	64
emails	Array 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 '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


pspId	The ID of the PSP.	[a-f 0-9]	32	Required for Option 1
divisionId	The ID of the division.	[a-f 0-9]	32	Required for Option 2
merchantId	The ID of the merchant.	[a-f 0-9]	32	Required for Option 3
channelId	The ID of the channel.	[a-f 0-9]	32	Required for Option 4


webhookId	The ID of the webhook.	[a-f 0-9]	32	Required

Data parameters

No parameters required.

Success response


200: OK	The 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 'credentials: <username>:<password>'

Response samples

{}

{
  "error": {
    "code": "200.300.406",
    "message": "Webhook not found: ab12cd34ef56ab12cd34ef56ab12cd106"
  }
}

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


pspId	The ID of the PSP.	[a-f 0-9]	32	Required for Option 1
divisionId	The ID of the division.	[a-f 0-9]	32	Required for Option 2
merchantId	The ID of the merchant.	[a-f 0-9]	32	Required for Option 3
channelId	The ID of the channel.	[a-f 0-9]	32	Required for Option 4


webhookId	The ID of the webhook.	[a-f 0-9]	32	Required

Data parameters

No parameters required.

Success response


200: OK	The 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.

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 '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
  }
}

{
  "error": {
    "code": "200.300.406",
    "message": "Webhook not found: ab12cd34ef56ab12cd34ef56ab12cd106"
  }
}

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.

Review point

The Method value is missing in the Confluence export; POST taken from the Webhook operations overview.

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 'credentials: <username>:<password>' \
  -F '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
  }
}

{
  "error": {
    "code": "200.300.406",
    "message": "Webhook not found: ab12cd34ef56ab12cd34ef56ab12cd106"
  }
}