Skip to end of metadata
Go to start of metadata

Introduction

Trustly is a payment initiation service provided by Trustly Group AB for customers of >3.300 banks in 29 European countries. A user intending to pay via Trustly will be directed to the user bank's online banking website. After authentication the user will confirm a pre-filled giro transfer (usually by TAN). The merchant is notified about an successful payment immediately and Trustly will provide a payment guarantee.

Preauthorization

Request "preauthorization"

Common Parameter

RequiredComment

aid

+

Sub-Account ID, defined by PAYONE

Format

NUMERIC(5..6)

+

Fixed Value

sb

reference

+

Merchant reference number for the payment process (case insensitive)

Format

CHAR(1..20)
Permitted Symbols
[0-9][a-z][A-Z], .,-,_,/

amount

+

Specifies the total gross amount of a payment transaction.

Value is given in smallest currency unit, e.g. Cent of Euro; Pence of Pound sterling; Öre of Swedish krona.

The amount must be less than or equal to the amount of the corresponding booking.

Format

NUMERIC(1..10)

Permitted values

max. +/- 19 999 999 99

currency

+

Fixed Value
EUR

param

-

Individual parameter (per payment process)

Format

CHAR(1..255)

narrative_text

-

Dynamic text element on account statements

Format

CHAR(1..81)

(3 lines with 27 characters each) and credit card statements.

customer_is_present

-

Indicates whether customer is “present” and can enter their data in the shop (=yes). Or customer is not present and can not enter any data (=no).

Format

LIST 

Permitted Values

yes
no

Parameter ( personal data )

customerid

-

Merchant's customer ID, defined by you / merchant to refer to the customer record

Format

CHAR(1..20)
Permitted Symbols
[0-9, a-z, A-Z, .,-,_,/]
  • "customerid" can be used to identify a customer record.
  • If "customerid" is used then stored customer data are loaded automatically.

userid

-

PAYONE User ID, defined by PAYONE

Format

NUMERIC(6..12)

businessrelation

o

Value specifies business relation between merchant and customer

Format

LIST 
valueComment

b2c

Indicates business to private customer

b2b

indicates business to business customer (company)

salutation

-

The customer's salutation

Format

CHAR(1..10)

title

-

Title of the customer

Format

CHAR(1..20)

Samples

Dr
Prof.
Dr.-Ing.

firstname

-

First name of customer; optional if company is used, i.e.: you may use

  • "company"
  • or "lastname"
  • or "firstname" plus "lastname"

Format

CHAR(1..50)

lastname

+

Last name of customer; optional if company is used, i.e.: you may use

  • "company"
  • or "lastname"
  • or "firstname" plus "lastname"

Format

CHAR(2..50)

company

-

Company name of customer; The company name is optional if lastname is used, i.e.: you may use

  • "company"
  • or "lastname"
  • or "firstname" plus "lastname"

Format

CHAR(2..50)

street

-

Street number and name (required: at least one character)

Format

CHAR(1..50)

addressaddition

-

Specifies an additional address line for the invoice address of the customer.

Format

CHAR(1..50)

Samples

7th floor
c/o Maier

zip

-

Postcode

Format

CHAR(2..10)
Permitted Symbols
[0-9][A-Z][a-z][_.-/ ]

city

-

City of customer

Format

CHAR(2..50)

country

+

Specifies country of address for the customer

Format

LIST 

Permitted values

ISO 3166 2-letter-codes

Samples

DE
GB
US

Some countries require additional information in parameter "state"

state

-

Specifies state / region of country for the customer.
"state" is required for these countries: US, CA, CN, JP, MX, BR, AR, ID, TH, IN and must not be used for all other countries.

Format

LIST

Permitted values


Samples US

AK
AL
AR

Samples CA

AB
BC

email

-

email-address of customer

Format

CHAR(5..254)
Permitted Symbols
RFC 5322

telephonenumber

-

Phone number of customer

Format

CHAR(1..30)

birthday

-

Date of birth of customer


Format

DATE(8), YYYYMMDD

Samples

20190101
19991231

language

-

Language indicator (ISO 639) to specify the language that should be presented to the customer (e.g. for error messages, frontend display).

If the language is not transferred, the browser language will be used. For a non-supported language English will be used.

Format

LIST 

Permitted values

ISO 639-1 (Language) 2-letter-codes

vatid

-

VAT identification number. Used for b2b transactions to indicate VAT number of customer.

Format

CHAR(1..50)

gender

-

Gender of customer (female / male / diverse* )

Format

LIST 

Permitted values

f    
m
d

* currently not in use

personalid

-

Person specific numbers or characters, e.g. number of passport / ID card

Format

CHAR(1..32)
Permitted Symbols
[0-9][A-Z][a-z][+-./()]

ip

-

Customer's IP-V4-address (123.123.123.123) or IP-V6-address

Format

CHAR(1..39)

Parameter ( delivery data )

shipping_firstname

-

First name of delivery address

Format

CHAR(1..50)

shipping_lastname

-

Surname of delivery address

Format

CHAR(1..50)

shipping_company

-

Company Name of the delivery address

Format

CHAR(2..50)

shipping_street

-

Street number and name of delivery address

Format

CHAR(2..50)

shipping_zip

-

Postcode of delivery address

Format

CHAR(2..10)
Permitted Symbols
[0-9][A-Z][a-z][_.-/ ]

shipping_addressaddition

-

Specifies an additional address line for the delivery address of the customer, e.g. "7th floor", "c/o Maier".

Format

CHAR(1..50)

shipping_city

-

City of delivery address

Format

CHAR(2..50)

shipping_state

o

Specifies state of country of delivery address for the customer
"shipping_state" is required for these countries: US, CA, CN, JP, MX, BR, AR, ID, TH, IN (if shipping_country is given) and must not be used in all other countries.

Format

LIST

Permitted values


Samples US

AK
AL
AR

Samples CA

AB
BC

shipping_country

-

Specifies country of delivery address for the customer

Format

LIST 

Permitted values

ISO 3166 2-letter-codes

Samples

DE
GB
US

Some countries require additional information in parameter shipping_state

Parameter ( online transfer )

onlinebanktransfertype

+

Fixed Value
TRL

bankcountry

+

Account type/ country for use with BBAN (i.e. bankcode, bankaccount): DE

DE: Mandatory with bankcode, bankaccount, optional with IBAN

For other countries than DE please use IBAN or IBAN/BIC

Format

LIST 

Permitted Values
DE
DK
EE
ES
FI
IT 
MT
NL
NO
PL
SE

iban

o

Bank Identifier Code to be used for payment or to be checked

Format

CHAR(8 or 11) Only capital letters and digits, no spaces
Permitted Symbols
[0-9][A-Z]

BIC is optional for all Bank transfers within SEPA. For Accounts from Banks outside of SEPA, BIC is still required. 

bic

o

Bank Identifier Code to be used for payment or to be checked

Format

CHAR(8 or 11) Only capital letters and digits, no spaces
Permitted Symbols
[0-9][A-Z]

BIC is optional for all Bank transfers within SEPA. For Accounts from Banks outside of SEPA, BIC is still required. 

successurl

+

URL for "payment successful"

Format

CHAR(2..255)

Scheme

<scheme>://<host>/<path>
<scheme>://<host>/<path>?<query>

scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

errorurl

+

URL for "faulty payment"

Format

CHAR(2..255)

Scheme

<scheme>://<host>/<path>
<scheme>://<host>/<path>?<query>

scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

backurl

+

URL for "Back" or "Cancel"

Format

CHAR(2..255)

Scheme

<scheme>://<host>/<path>
<scheme>://<host>/<path>?<query>

scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}


preauthorization example request
mid=23456 (your mid)
portalid=12345123 (your portalid)
key=abcdefghijklmn123456789 (your key)
api_version=3.10
mode=test (set to „live“ for live-requests)
request=preauthorization
encoding=UTF-8

aid=12345 (your aid)
clearingtype=sb
reference=Ref123456
amount=300
currency=EUR
lastname=Mustermann
country=DE

onlinebanktransfertype=TRL
bankcountry=DE



successurl=http://www.your-success.url
errorurl=http://www.your-error.url
backurl=http://www.your-back.url



Response "preauthorization"

Common Parameter

RequiredComment

status

+

Permitted Values
REDIRECT
ERROR

Parameter (REDIRECT)

txid

+

The txid specifies the payment process within the PAYONE platform

Format

NUMERIC(9..12)

userid

+

PAYONE User ID, defined by PAYONE

Format

NUMERIC(6..12)

redirecturl

+

Redirect URL → zMerchant system has to redirect customer to this URL to complete payment

Format

CHAR(2..2000)

Parameter (ERROR)

errorcode

+

In case of error the PAYONE Platform returns an error code for your internal usage.

Format

NUMERIC(1..6)

errormessage

+

In case of error the PAYONE Platform returns an error message for your internal usage.

Format

CHAR(1..1024)

customermessage

-

The customermessage is returned to your system in order to be displayed to the customer.

(Language selection is based on the end customer's language, parameter "language")

Format

CHAR(1..1024)



preauthorization example response REDIRECT
status=REDIRECT
redirecturl=http://www.aliasregistrationpage.com
txid=345678901
userid=123456789


Capture  / Multi-partial Capture


Request "capture"

Common Parameter

Required

Short explanation

txid

+

The txid specifies the payment process within the PAYONE platform

Format

NUMERIC(9..12)

sequencenumber

o

Sequence number for this transaction within the payment process (1..n), e.g. PreAuthorization: 0, 1. Capture: 1, 2. Capture: 2

Required for multi partial capture (starting with the 2nd capture)

Format

NUMERIC(1..3)

Permitted values

0..127

amount

+

Specifies the total gross amount of a payment transaction.

Value is given in smallest currency unit, e.g. Cent of Euro; Pence of Pound sterling; Öre of Swedish krona.

The amount must be less than or equal to the amount of the corresponding booking.

Format

NUMERIC(1..10)

Permitted values

max. +/- 19 999 999 99

currency

+


Fixed Value
EUR

narrative_text

-

Dynamic text element on account statements

Format

CHAR(1..81)

(3 lines with 27 characters each) and credit card statements.

capture example request
mid=23456 (your mid)
portalid=12345123 (your portalid)
key=abcdefghijklmn123456789 (your key)
api_version=3.10
mode=test (set to „live“ for live-requests)
request=capture
encoding=UTF-8

txid=345678901
amount=300
currency=EUR


Response "capture"

Common Parameter

Required

Comment

status

+

Permitted Values
APPROVED
PENDING ???
ERROR

Parameter (APPROVED)

txid

+

The txid specifies the payment process within the PAYONE platform

Format

NUMERIC(9..12)

settleaccount

o

Provides information about whether a settlement of balances has been carried out.

Format

LIST 
ValueComment
yesSettlement of outstanding balances has been carried out.
noSettlement of outstanding balances has not been carried out.

Parameter (PENDING)

txid

+

The txid specifies the payment process within the PAYONE platform

Format

NUMERIC(9..12)

userid

+

PAYONE User ID, defined by PAYONE

Format

NUMERIC(6..12)

Parameter (ERROR)

errorcode

+

In case of error the PAYONE Platform returns an error code for your internal usage.

Format

NUMERIC(1..6)

errormessage

+

In case of error the PAYONE Platform returns an error message for your internal usage.

Format

CHAR(1..1024)

capture example response
status=APPROVED
txid=345678901
settleaccount=no


Authorization


Request "authorization"

Common Parameter

RequiredShort explanation

aid

+

Sub-Account ID, defined by PAYONE

Format

NUMERIC(5..6)

clearingtype

+

Fixed Value
sb

reference

+

Merchant reference number for the payment process (case insensitive)

Format

CHAR(1..20)
Permitted Symbols
[0-9][a-z][A-Z], .,-,_,/

amount

+

Specifies the total gross amount of a payment transaction.

Value is given in smallest currency unit, e.g. Cent of Euro; Pence of Pound sterling; Öre of Swedish krona.

The amount must be less than or equal to the amount of the corresponding booking.

Format

NUMERIC(1..10)

Permitted values

max. +/- 19 999 999 99

currency

+


Fixed Value
EUR

param

-

Individual parameter (per payment process)

Format

CHAR(1..255)

narrative_text

-

Dynamic text element on account statements

Format

CHAR(1..81)

(3 lines with 27 characters each) and credit card statements.

customer_is_present

-

Indicates whether customer is “present” and can enter their data in the shop (=yes). Or customer is not present and can not enter any data (=no).

Format

LIST 

Permitted Values

yes
no

transaction_param

-

Optional parameter for merchant information (per payment request)

Format

CHAR(1..50)
Permitted Symbols
[0-9][A-Z][a-z][.-_/]

Parameter ( personal data )

customerid

-

Merchant's customer ID, defined by you / merchant to refer to the customer record

Format

CHAR(1..20)
Permitted Symbols
[0-9, a-z, A-Z, .,-,_,/]
  • "customerid" can be used to identify a customer record.
  • If "customerid" is used then stored customer data are loaded automatically.

userid

-

PAYONE User ID, defined by PAYONE

Format

NUMERIC(6..12)

businessrelation

o

Value specifies business relation between merchant and customer

Format

LIST 
valueComment

b2c

Indicates business to private customer

b2b

indicates business to business customer (company)

salutation

-

The customer's salutation

Format

CHAR(1..10)

title

-

Title of the customer

Format

CHAR(1..20)

Samples

Dr
Prof.
Dr.-Ing.

firstname

o

First name of customer; optional if company is used, i.e.: you may use

  • "company"
  • or "lastname"
  • or "firstname" plus "lastname"

Format

CHAR(1..50)

lastname

+

Last name of customer; optional if company is used, i.e.: you may use

  • "company"
  • or "lastname"
  • or "firstname" plus "lastname"

Format

CHAR(2..50)

company

-

Company name of customer; The company name is optional if lastname is used, i.e.: you may use

  • "company"
  • or "lastname"
  • or "firstname" plus "lastname"

Format

CHAR(2..50)

street

-

Street number and name (required: at least one character)

Format

CHAR(1..50)

addressaddition

-

Specifies an additional address line for the invoice address of the customer.

Format

CHAR(1..50)

Samples

7th floor
c/o Maier

zip

-

Postcode

Format

CHAR(2..10)
Permitted Symbols
[0-9][A-Z][a-z][_.-/ ]

city

-

City of customer

Format

CHAR(2..50)

state

-

Specifies state / region of country for the customer.
"state" is required for these countries: US, CA, CN, JP, MX, BR, AR, ID, TH, IN and must not be used for all other countries.

Format

LIST

Permitted values


Samples US

AK
AL
AR

Samples CA

AB
BC

country

+

Specifies country of address for the customer

Format

LIST 

Permitted values

ISO 3166 2-letter-codes

Samples

DE
GB
US

Some countries require additional information in parameter "state"

email

-

email-address of customer

Format

CHAR(5..254)
Permitted Symbols
RFC 5322

telephonenumber

-

Phone number of customer

Format

CHAR(1..30)

birthday

-

Date of birth of customer


Format

DATE(8), YYYYMMDD

Samples

20190101
19991231

language

-

Language indicator (ISO 639) to specify the language that should be presented to the customer (e.g. for error messages, frontend display).

If the language is not transferred, the browser language will be used. For a non-supported language English will be used.

Format

LIST 

Permitted values

ISO 639-1 (Language) 2-letter-codes

vatid

-

VAT identification number. Used for b2b transactions to indicate VAT number of customer.

Format

CHAR(1..50)

gender

-

Gender of customer (female / male / diverse* )

Format

LIST 

Permitted values

f    
m
d

* currently not in use

personalid

-

Person specific numbers or characters, e.g. number of passport / ID card

Format

CHAR(1..32)
Permitted Symbols
[0-9][A-Z][a-z][+-./()]

ip

-

Customer's IP-V4-address (123.123.123.123) or IP-V6-address

Format

CHAR(1..39)

Parameter ( delivery data )

shipping_firstname

-

First name of delivery address

Format

CHAR(1..50)

shipping_lastname

-

Surname of delivery address

Format

CHAR(1..50)

shipping_company

-

Company Name of the delivery address

Format

CHAR(2..50)

shipping_street

-

Street number and name of delivery address

Format

CHAR(2..50)

shipping_addressaddition

-

Specifies an additional address line for the delivery address of the customer, e.g. "7th floor", "c/o Maier".

Format

CHAR(1..50)

shipping_zip

-

Postcode of delivery address

Format

CHAR(2..10)
Permitted Symbols
[0-9][A-Z][a-z][_.-/ ]

shipping_city

-

City of delivery address

Format

CHAR(2..50)

shipping_state

-

Specifies state of country of delivery address for the customer
"shipping_state" is required for these countries: US, CA, CN, JP, MX, BR, AR, ID, TH, IN (if shipping_country is given) and must not be used in all other countries.

Format

LIST

Permitted values


Samples US

AK
AL
AR

Samples CA

AB
BC

shipping_country

-

Specifies country of delivery address for the customer

Format

LIST 

Permitted values

ISO 3166 2-letter-codes

Samples

DE
GB
US

Some countries require additional information in parameter shipping_state

Parameter ( online transfer )         

onlinebanktransfertype

+

Fixed Value

TRL

bankcountry

+

Account type/ country for use with BBAN (i.e. bankcode, bankaccount): DE

DE: Mandatory with bankcode, bankaccount, optional with IBAN

For other countries than DE please use IBAN or IBAN/BIC

Format

LIST 

Permitted Values
DE
DK
EE
ES
FI
IT 
MT
NL
NO
PL
SE

iban

-

IBAN to be used for payment or to be checked

Format

CHAR(10..34)
Permitted Symbols
[0-9][A-Z]

bic

-

Bank Identifier Code to be used for payment or to be checked

Format

CHAR(8 or 11) Only capital letters and digits, no spaces
Permitted Symbols
[0-9][A-Z]

BIC is optional for all Bank transfers within SEPA. For Accounts from Banks outside of SEPA, BIC is still required. 

successurl

+

URL for "payment successful"

Format

CHAR(2..255)

Scheme

<scheme>://<host>/<path>
<scheme>://<host>/<path>?<query>

scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

errorurl

+

URL for "faulty payment"

Format

CHAR(2..255)

Scheme

<scheme>://<host>/<path>
<scheme>://<host>/<path>?<query>

scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

backurl

+

URL for "Back" or "Cancel"

Format

CHAR(2..255)

Scheme

<scheme>://<host>/<path>
<scheme>://<host>/<path>?<query>

scheme-pattern: [a-zA-Z]{1}[a-zA-Z0-9]{1,9}

authorization example request
mid=23456 (your mid)
portalid=12345123 (your portalid)
key=abcdefghijklmn123456789 (your key)
api_version=3.10
mode=test (set to „live“ for live-requests)
request=authorization
encoding=UTF-8

aid=12345 (your aid)
clearingtype=sb
reference=Ref123456
amount=300
currency=EUR
lastname=Mustermann
country=DE

onlinebanktransfertype=TRL
bankcountry=DE



successurl=http://www.your-success.url
errorurl=http://www.your-error.url
backurl=http://www.your-back.url


Response "authorization"

Common Parameter

Required

Comment

status

+


Permitted Values
REDIRECT
ERROR

Parameter (REDIRECT)

txid

+

The txid specifies the payment process within the PAYONE platform

Format

NUMERIC(9..12)

userid

+

PAYONE User ID, defined by PAYONE

Format

NUMERIC(6..12)

redirecturl

+

Redirect URL → zMerchant system has to redirect customer to this URL to complete payment

Format

CHAR(2..2000)

Parameter (ERROR)

errorcode

+

In case of error the PAYONE Platform returns an error code for your internal usage.

Format

NUMERIC(1..6)

errormessage

+

In case of error the PAYONE Platform returns an error message for your internal usage.

Format

CHAR(1..1024)

customermessage

-

The customermessage is returned to your system in order to be displayed to the customer.

(Language selection is based on the end customer's language, parameter "language")

Format

CHAR(1..1024)

authorization example response
status=REDIRECT
redirecturl=http://www.aliasregistrationpage.com
txid=345678901
userid=123456789

Debit

Request "debit"

Common Parameter

Required

Short explanation

txid

+

The txid specifies the payment process within the PAYONE platform

Format

NUMERIC(9..12)

sequencenumber

+

Sequence number for this transaction within the payment process (1..n), e.g. PreAuthorization: 0, 1. Capture: 1, 2. Capture: 2

Required for multi partial capture (starting with the 2nd capture)

Format

NUMERIC(1..3)

Permitted values

0..127

amount

+

Gross amount of debit (in smallest currency unit! e.g. cent, max. 19 999 999 99)

Credit: amount < 0

Payment request: amount > 0

The amount must be less than or equal to the amount of the outstanding payment request of the corresponding booking.

Format

NUMERIC(1..10), max. value +/- 19 999 999 99

currency

+

Specifies currency for this transaction


Format

LIST 

Permitted values

 ISO 4217 (currencies) 3-letter-codes

Samples

EUR
USD
GBP

narrative_text

-

Dynamic text element on account statements

Format

CHAR(1..81)

(3 lines with 27 characters each) and credit card statements.

clearingtype

-

Use for changes of payment type - only to select new payment type.

Format

LIST 
valueCommentDescription
recInvoice

use_customerdata

-

Use account details from debtor's master data

Format

LIST 
ValueComment

yes

Uses current account details from debtor's master data (default)

no

Uses the last known account details in the payment process

transaction_param

-

Optional parameter for merchant information (per payment request)

Format

CHAR(1..50)
Permitted Symbols
[0-9][A-Z][a-z][.-_/]

Parameter ( online transfer - for refunds only )

iban

o

IBAN to be used for payment or to be checked

Format

CHAR(10..34)
Permitted Symbols
[0-9][A-Z]

bic

o

Bank Identifier Code to be used for payment or to be checked

Format

CHAR(8 or 11) Only capital letters and digits, no spaces
Permitted Symbols
[0-9][A-Z]

BIC is optional for all Bank transfers within SEPA. For Accounts from Banks outside of SEPA, BIC is still required. 

bankcountry

o

Account type/ country for use with BBAN (i.e. bankcode, bankaccount): DE

DE: Mandatory with bankcode, bankaccount, optional with IBAN

For other countries than DE please use IBAN or IBAN/BIC

Format

LIST 

bankaccount

o

Account number (BBAN)

  • DE: bankcountry, bankcode and bankaccount may be used. Then IBAN will be generated by PAYONE platform and used for SEPA transactions.
  • Not DE: Please use IBAN or IBAN / BIC.

Format

NUMERIC(1..10)

bankcode

o

Sort code (BBAN) (only in DE)

  • DE: bankcountry, bankcode and bankaccount may be used. Then IBAN will be generated by PAYONE platform and used for SEPA transactions.
  • Not DE: Please use IBAN or IBAN / BIC.

Format

NUMERIC(8)

mandate_identification

o

A SEPA mandate can be created if a payment is initiated (amount > 0). Can be used to enforce a merchant specific mandate identification. The mandate_identification has to be unique.

Format

CHAR(1..35)
Permitted Symbols
[A-Z,a-z,0-9,+,-,.,(,)]

If the mandate_identification is not set PAYONE will create an unique mandate identification (pattern: PO-nnnnnnnnnn).

PPS (PAYONE Payment Service): This parameter must not be used! For PPS the PAYONE platform defines the mandate_identification

bankaccountholder

-

Account holder


Format

CHAR(1..50)


debit example request
mid=23456 (your mid)
portalid=12345123 (your portalid)
key=abcdefghijklmn123456789 (your key)
api_version=3.10
mode=test (set to „live“ for live-requests)
request=capture
encoding=UTF-8

txid=345678901
sequencenumber=1
amount=1000
currency=EUR


Response "debit"

Common Parameter

Required

Comment

status

+

Permitted Values
APPROVED
ERROR

Parameter (APPROVED)

txid

+

The txid specifies the payment process within the PAYONE platform

Format

NUMERIC(9..12)

settleaccount

+

Provides information about whether a settlement of balances has been carried out.

Format

LIST 
ValueComment
yesSettlement of outstanding balances has been carried out.
noSettlement of outstanding balances has not been carried out.

Parameter (ERROR)

errorcode

+

In case of error the PAYONE Platform returns an error code for your internal usage.

Format

NUMERIC(1..6)

errormessage

-

In case of error the PAYONE Platform returns an error message for your internal usage.

Format

CHAR(1..1024)

customermessage

-

The customermessage is returned to your system in order to be displayed to the customer.

(Language selection is based on the end customer's language, parameter "language")

Format

CHAR(1..1024)

debit example response
status=APPROVED
txid=345678901
settleaccount=no

Refund


Request "refund"

Common Parameter

RequiredShort explanation

txid

+

The txid specifies the payment process within the PAYONE platform

Format

NUMERIC(9..12)

sequencenumber

+

Sequence number for this transaction within the payment process (1..n), e.g. PreAuthorization: 0, 1. Capture: 1, 2. Capture: 2

Required for multi partial capture (starting with the 2nd capture)

Format

NUMERIC(1..3)

Permitted values

0..127

amount

+

Amount of refund (in smallest currency unit! e.g. cent, max. 19 999 999 99). The amount must be less than or equal to the amount of the corresponding booking.

Always provide a negative amount

Format

NUMERIC(1..10), max. value +/- 19 999 999 99

currency

+

Specifies currency for this transaction


Format

LIST 

Permitted values

 ISO 4217 (currencies) 3-letter-codes

Samples

EUR
USD
GBP

narrative_text

-

Dynamic text element on account statements

Format

CHAR(1..81)

(3 lines with 27 characters each) and credit card statements.

use_customerdata

-

Use account details from debtor's master data

Format

LIST 
ValueComment

yes

Uses current account details from debtor's master data (default)

no

Uses the last known account details in the payment process

transaction_param

-

Optional parameter for merchant information (per payment request)

Format

CHAR(1..50)
Permitted Symbols
[0-9][A-Z][a-z][.-_/]

refund example request
mid=23456 (your mid)
portalid=12345123 (your portalid)
key=abcdefghijklmn123456789 (your key)
api_version=3.10
mode=test (set to „live“ for live-requests)
request=capture
encoding=UTF-8

txid=345678901
sequencenumber=2
amount=1000
currency=EUR



Response "refund"

Common Parameter

Required

Comment

status

+

Permitted Values
APPROVED
PENDING
ERROR

Parameter (APPROVED)

txid

+

The txid specifies the payment process within the PAYONE platform

Format

NUMERIC(9..12)

Parameter (PENDING)

txid

+

The txid specifies the payment process within the PAYONE platform

Format

NUMERIC(9..12)

Parameter (ERROR)

errorcode

+

In case of error the PAYONE Platform returns an error code for your internal usage.

Format

NUMERIC(1..6)

errormessage

+

In case of error the PAYONE Platform returns an error message for your internal usage.

Format

CHAR(1..1024)



refund example response
status=APPROVED
txid=345678901


Specials

  • Partial Captures are supported but the account of the customer will be debit with the Preauthorization ?????
  • Partial Refunds are not supported ?????
  • Reversal is not supported ?????

Examples of Usage

Sale

Order & Delivery

Returns


  • No labels