How to use JSON-Responses

The PAYONE Platform API is designed for key-/value-pairs. However you may use the PAYONE API with JSON-responses as well.
Therefore

  • the HTTP Accept header in the API request has to be set to “Accept: application/json” to indicate that a JSON response should be sent.
  • Only the response will be in JSON – the request itself will still be key/value.
  • The Parameter encoding must be included in the request and the encoding that is entered is also returned with the response

---end

JSON, data structure

Below you’ll find a table with the original Response-parameter and the JSON-structure/-element.

JSON, common data

API response parameter

JSON structure

JSON element

status

---

Status

txid

---

TxId

userid

---

UserId

accessid

---

AccessId

settleaccount

---

SettleAccount

vxid

---

VxId

vaid

---

VaId

redirecturl

---

RedirectUrl

workorderid

---

WorkOrderId

usertoken

---

UserToken

JSON, Error-Handling

API response parameter

JSON structure

JSON element

errorcode

Error

ErrorCode

errormessage

Error

ErrorMessage

customermessage

Error

CustomerMessage

JSON, customer data (person, address, ...)

API response parameter

JSON structure

JSON element

Comments

salutation

Person

Salutation
title

Person

Title
firstname

Person

FirstName
lastname

Person

LastName
birthday

Person

DateOfBirth Format “yyyymmdd”
personalid

Person

PersonalId
language

Person

LanguageCode ISO 639, e.g. "de"
language

Person

LanguageName English language name, e.g. "German"
gender

Person

GenderCode MALE | FEMALE
street

Address

Street
addressaddition

Address

AddressAddition
zip

Address

Zip
city

Address

City
country

Address

CountryCode ISO 3166-2, e.g. "DE"
country

Address

CountryName English country name, e.g. "Germany"
state

Address

StateCode ISO 3166-2 region code

state

Address

StateName
shipping_firstname

ShippingAddress

FirstName
shipping_lastname

ShippingAddress

LastName
shipping_company

ShippingAddress

Company
shipping_street

ShippingAddress

Street
shipping_addressaddition

ShippingAddress

AddressAddition
shipping_zip

ShippingAddress

Zip ISO 3166-2, e.g. "DE"
shipping_city

ShippingAddress

City English country name, e.g. "Germany"
shipping_country

ShippingAddress

CountryCode
shipping_country

ShippingAddress

CountryName
shipping_state

ShippingAddress

StateCode
shipping_state

ShippingAddress

StateName
company

Company

CompanyName
vatid

Company

VatId
telephonenumber

ContactData

Phone
email

ContactData

Mail

JSON, Clearing-Data

API response parameter

JSON structure

JSON element

clearing_bankaccountholder

Clearing.BankAccount

BankAccountHolder

clearing_bankcountry

Clearing.BankAccount

BankCountry

clearing_bankaccount

Clearing.BankAccount

BankAccount

clearing_bankcode

Clearing.BankAccount

BankCode

clearing_bankiban

Clearing.BankAccount

Iban

clearing_bankbic

Clearing.BankAccount

Bic

clearing_bankcity

Clearing.BankAccount

BankCity

clearing_bankname

Clearing.BankAccount

BankName

clearing_instructionnote

Clearing

InstructionNote

clearing_legalnote

Clearing

LegalNote

clearing_duedate

Clearing

DueDate

clearing_reference

Clearing

Reference

JSON, Credit Card

API response parameter

JSON structure

JSON element

Comments

protect_result_avs

Risk

AvsResult

pseudocardpan

CreditCard

PseudoCardPan

truncatedcardpan

CreditCard

MaskedCardPan

In fact a masked credit card number (e.g. 411111xxxxxx1111) will be returned. So the JSON-name is more correct.

JSON, Credit Card -> 3DS

API response parameter

JSON structure

JSON element

xid

CreditCard.ThreeDS

Xid

acsurl

CreditCard.ThreeDS

AcsUrl

termurl

CreditCard.ThreeDS

TermUrl

pareq

CreditCard.ThreeDS

PaReq

md

CreditCard.ThreeDS

Md

JSON, Bank Accounts

API response parameter

JSON structure

JSON element

iban

BankAccount

Iban

bic

BankAccount

Bic

bankcountry

BankAccount

BankCountry

bankcode

BankAccount

BankCode

bankaccount

BankAccount

BankAccount

bankbranchcode

BankAccount

BankBranchCode

bankcheckdigit

BankAccount

BankCheckDigit

JSON, Direct Debit

API response parameter

JSON structure

JSON element

mandate_identification

Mandate

Identification

mandate_dateofsignature

Mandate

DateOfSignature

mandate_status

Mandate

Status

mandate_text

Mandate

HtmlText

creditor_identifier

Creditor

Identifier

creditor_name

Creditor

Name

creditor_street

Creditor

Street

creditor_zip

Creditor

Zip

creditor_city

Creditor

City

creditor_country

Creditor

Country

creditor_email

Creditor

Mail

clearing_date

Clearing

Date

clearing_amount

Clearing

Amount

JSON, AddressCheck / ConsumerScore

API response parameter

JSON structure

JSON element

secstatus

Risk

SecStatus

personstatus

Risk

PersonStatus

addressstatus

Risk

AddressStatus

identityconfirmed

Risk

IdentityConfirmed

secscore

Risk

SecScore

score

Risk

Score

scorevalue

Risk

ScoreValue

provideruserid

Risk

ProviderUserId

creditlimitvalue

Risk

CreditLimitValue

creditlimitcurrency

Risk

CreditLimitCurrency

firstname

Person

FirstName

lastname

Person

LastName

gender

Person

Gender

street

Address

Street

streetname

Address

StreetName

streetnumber

Address

StreetNumber

zip

Address

Zip

city

Address

City

legalform

Company

LegalForm

foundingdate

Company

FoundationDate

taxid

Company

TaxId

JSON, add_paydata

API response parameter

JSON structure
(always „AddPayData“)

JSON element
(identical to Key)

add_paydata[allowedCardTypes]

AddPayData

allowedCardTypes

add_paydata[callbackUrl]

AddPayData

callbackUrl

add_paydata[merchantCheckoutId]

AddPayData

merchantCheckoutId

add_paydata[version]

AddPayData

version

add_paydata[b2b-installment]

AddPayData

b2b-installment

add_paydata[delivery-address-elv]

AddPayData

delivery-address-elv

…[key]

AddPayData

Key

---end