Skip to end of metadata
Go to start of metadata

Introduction

The "debit" request books an outstanding amount to the receivables account. This request can be used instead of the "refund" request. The request offers additional options that are not possible using "refund".

PAYONE Processing

This request is only available with PAYONE Business.

PAYONE Business

The submitted amount is booked as an outstanding payment on the transaction account or credited to said account.

Settlement of balances

The PAYONE Platform can carry out a settlement of balances for you. If a transaction account has a negative balance it can be captured or paid out in case of a positive balance. The means of payment used for the settlement are always the funds that have been deposited during the process.

If you set the parameter "settleaccount" to "no" using the "debit" request, a settlement is not carried out. Only a booking on the transaction account occurs. If you select the value "yes", however, the balance is automatically settled (captured or paid out) by the PAYONE Platform after the request has been carried out.

Please notice that the submitted amount does not necessarily correspond with the open balance which is subsequently captured or paid out. This is always the case if the balance was not settled before issuing the request!

If you only wish to settle the open balance without booking a new payment request enter zero as the amount and set the "settleaccount" value to "yes". This can be useful e.g. for a refund in the event of an overpayment by the customer or can be used for the repeated collection of an unpaid debit payment. Furthermore, the open balance can be collected using a different type of payment. For this purpose the corresponding payment data must be submitted. This process can e.g. be used for a subsequent collection of an invoice via direct debit or credit card.

Payment typeDescriptionComments

Credit card

The open balance is credited to or drawn from the customer's card.


Debit payment

The customer is reimbursed with the open balance
or the balance is collected by means of a debit payment.

For collecting money and refund: According to the new regulation on the transfer of funds (Geldtransferverordnung) address data (name, street, zip, city) is mandatory for cross border bank transfers (EEA / EWR), e.g.: CH, SM, MC, PM, JE, GG. This is mandatory from 2017-11-19.

Please use request “updateuser” to update customers address data.

This means that the whole address for bank transfers needs to be provided.

Online transfer

The customer is reimbursed with the open balance,
collection is not possible.

For refund for Giropay: According to the new regulation on the transfer of funds (Geldtransferverordnung) address data (name, street, zip, city) is mandatory for cross border bank transfers (EEA / EWR), e.g.: CH, SM, MC, PM, JE, GG. This is mandatory from 2017-11-19.

Please use request “updateuser” to update customers address data.

This means that the whole address for bank transfers needs to be provided.

e-wallet

The open balance is credited to the customer's e-wallet account,
collection is not possible


Prepayment

The customer is reimbursed with the open balance,
collection is not possible.

For refund: According to the new regulation on the transfer of funds (Geldtransferverordnung) address data (name, street, zip, city) is mandatory for cross border bank transfers (EEA / EWR), e.g.: CH, SM, MC, PM, JE, GG. This is mandatory from 2017-11-19.

Please use request “updateuser” to update customers address data.

This means that the whole address for bank transfers needs to be provided.

Invoice

The customer is reimbursed with the open balance,
collection is not possible.

For refund: According to the new regulation on the transfer of funds (Geldtransferverordnung) address data (name, street, zip, city) is mandatory for cross border bank transfers (EEA / EWR), e.g.: CH, SM, MC, PM, JE, GG. This is mandatory from 2017-11-19.

Please use request “updateuser” to update customers address data.

This means that the whole address for bank transfers needs to be provided.

Cash on delivery

The customer is reimbursed with the open balance,
collection is not possible.

For refund: According to the new regulation on the transfer of funds (Geldtransferverordnung) address data (name, street, zip, city) is mandatory for cross border bank transfers (EEA / EWR), e.g.: CH, SM, MC, PM, JE, GG. This is mandatory from 2017-11-19.

Please use request “updateuser” to update customers address data.

This means that the whole address for bank transfers needs to be provided.


Request "debit"

Common Parameter

Required

FormatShort 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 ( PAYONE Business )

settleaccount

-


Carry out settlement of outstanding balances. The request is booked and the resulting balance is settled by means of a collection, e.g. a refund.

Format

LIST
ValueComment
yesSettlement of outstanding balances is carried out.
noDo not carry out settlement of outstanding balances, book request only.
autoThe system decides - depending on type of payment and balance - if a settlement of balances can be carried out or not. (default)

transactiontype

-


Type of payment request

Format

LIST
ValueComment

RL

Direct debit return fee

MG

Dunning charge

VZ

Default interest

VD

Delivery charges

FD

Payment request (default for amount > 0)

GT

Credit (default for amount < 0)

RT

Returns

booking_date

-


Booking date (YYYYMMDD)

Format

DATE(8), YYYYMMDD

document_date

-


Document date (YYYYMMDD)

Format

DATE(8), YYYYMMDD

Parameter ( Invoice / prepayment / online transfer - for refunds only )

Parameter ( Debit payment - change of type of payment or refund 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)

Parameter ( credit card - change of type of payment only )

cardpan

+


Primary account number of credit card

Format

NUMERIC(13..19)

  • if your system handles "cardpan" directly you can not be PCI DSS SAQ A compliant.
  • for simple PCI DSS SAQ A compliance please use PAYONE hosted iFrames together with pseudocardpan.

cardtype

+


Card type of credit card

Format

LIST
valueCommentBIN-Range for automatic card type detection

V

Visa

4

M

MasterCard

51-55,2221-2720

A

American Express

34, 37
DDiners / Discover

300-305,3095,36,38,39

601, 64, 65

CDiscover

J

JCB

3528-3589

O

Maestro International

50, 56-58,602, 61, 620, 627, 63, 67
PChina Union Pay62212600-62299800,624-626, 6282-6288
UUATP / Airplus1220, 1920 -> coming soon; not available yet
Ggirocard68 *

*girocard is currently only viable for e-commerce-payments via Apple Pay.

cardexpiredate

+


Credit card expiry date YYMM


Format

NUMERIC(4), YYMM

cardcvc2

o


Credit card security number

Format

NUMERIC(3..4)

For SAQ A compliance: PAYONE Frontend hosted iFrame must be used. This parameter must not be used.

cardissuenumber

-


Card issue number (only Maestro UK cards)

Format

NUMERIC(1..2)

cardholder

-


Cardholder of credit card.


Format

CHAR(1..50)

pseudocardpan

o


Pseudo primary account number for a credit card.

Format

NUMERIC(16..19)

Parameter ( BillSAFE, Klarna, module Invoicing )

invoiceid

-


Merchant's invoice number

Format

CHAR(1..20)

invoice_deliverymode

-


Parameter defines how documents like invoice, credit notes and reminders should be sent to the customer.

Format

LIST
ValueComments

M

Postal Mail

P

PDF (via email)

N

no delivery


invoiceappendix

-


Dynamic text on the invoice

Format

CHAR(1..255)

invoice_deliverydate

-


Delivery date (YYYYMMDD)

Format

DATE(8), YYYYMMDD

invoice_deliveryenddate

-


Delivery end date (YYYYMMDD)

Format

DATE(8), YYYYMMDD

financingtype

+


Used with "clearingtype=fnc" to identify Financing type

Format

LIST

ValueCommentServer-APIClient-APIFrontend

RPV

Ratepay Open Invoice

(tick)(tick)(tick)

RPS

Ratepay Installments

(tick)(tick)

RPP

Ratepay Prepayment

(tick)(tick)(tick)

RPD

Ratepay Direct Debit

(tick)(tick)(tick)

PYV

Unzer Invoice

(tick)(tick)

PYS

Unzer Installment

(tick)(tick)

PYM

Unzer Monthly

(tick)(tick)

PYD

Unzer Direct Debit

(tick)(tick)
PPIPayPal Installment(tick)(tick)

KLV

Klarna Checkout Invoice

(tick)(tick)

KLS

Klarna Checkout Installment

(tick)(tick)
KISKlarna Payments "Slice it" (Installments)(tick)

KIVKlarna Payments "Pay now" (Invoice)(tick)

KDDKlarna Payments "Pay now" (Direct Debit)(tick)

KBTKlarna Payments "Pay now" (Bank Transfer)(tick)

it[n]

+


Parameter it[n] specifies the item type of a shopping cart item.

Format

LIST

Array

Array elements [n] starting with [1]; serially numbered; max [400]


it[n]

Comments


goodsGoods
shipment

Shipping charges


handling

Handling fee

  • Not to be used with PDT
voucherVoucher / discount
  • Not to be used with PDT

id[n]

o


Product number, SKU, etc. of this item

Format

CHAR(1..32)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

Permitted Symbols
[0-9][A-Z][a-z][()[]{} +-_#/:]

pr[n]

o


Unit gross price of the item in smallest unit! e.g. cent

Format

NUMERIC(10) max. 19 999 999 99

Array

Array elements [n] starting with [1]; serially numbered; max [400]

no[n]

o


Quantity of this item

Format

NUMERIC(6)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

de[n]

o


Description of this item. Will be printed on documents to customer.

Format

CHAR(1..255)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

Example 
de[1]=Product 1
de[2]=Product 2
de[3]=Product 3
...
de[400]=Product 400

va[n]

-


VAT rate (% or bp)

Format

NUMERIC(4)

Array

Array elements [n] starting with [1]; serially numbered; max [400]

sd[n]

-


Delivery date (YYYYMMDD)

Format

DATE(8), YYYYMMDD

Array

Array elements [n] starting with [1]; serially numbered; max [400]

ed[n]

-


Delivery period end date (YYYYMMDD)

Format

DATE(8), YYYYMMDD

Array

Array elements [n] starting with [1]; serially numbered; max [400]


Response "debit"

Common Parameter

Required

Format

Comment

status

+

Default

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)


Content


  • No labels