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

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.

Overview

Credit card The amount is credited to the customer's card
Debit payment The customer is reimbursed with the corresponding amount

For collecting money and debit: 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 corresponding amount, Giropay: see footnote Debit payment

For debit 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 amount is credited to the customer's e-wallet account
Prepayment

The customer is reimbursed with the corresponding amount, see footnote Debit payment

For debit: 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 corresponding amount, see footnote Debit payment

For debit: 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 corresponding amount, see footnote Debit payment

For debit: 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.

Integration

POST Request - Debit
Account Parameters
request
required
Fixed Value: debit
mid
required
your merchant ID, 5-digit numeric
aid
required
your subaccount ID, 5-digit numeric
portalId
required
your Portal ID, 7-digit numeric
key
required
your key value, alpha-numeric

---end

common Parameters
txid
optional
Format NUMERIC(9..12) 

The txid specifies the payment process within the PAYONE platform.

sequencenumber
optional
Format NUMERIC(1..3)
Permitted values 0..127

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)

amount
optional
Format NUMERIC(1..10)
Permitted values max. +/- 19 999 999 99

Specifies the total gross amount of a payment transaction.

Value is given in smallest currency unit, e.g. Cent of Euro.

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

currency
optional
Format LIST
Permitted values ISO 4217 (currencies) 3-letter-codes
Samples
EUR
USD
GBP
Amount of debit (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
narrative_text
optional
Format CHAR(1..81)

Dynamic text element on account statements.

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

use_customerdata
optional
Format LIST
value Comment
yes Uses current account details from debtor's master data (default)
no Uses the last known account details in the payment process

Use account details from debtor's master data

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

Optional parameter for merchant information (per payment request)

---end

Parameters (invoice/prepayment/cash on delivery)
iban
optional
Format CHAR(10..34)
Permitted Symbols [0-9][A-Z]
IBAN to be used for payment or to be checked
bic
optional
Format CHAR(8 or 11) Only capital letters and digits, no spaces
Permitted Symbols [0-9][A-Z]

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

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

bankcountry
optional
Format LIST 

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

bankaccount
optional
Format NUMERIC(1..10)

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.

bankcode
optional
Format NUMERIC(8)

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.

---end

Parameter (Invoicing)
invoiceid
optional
Format CHAR(1..20)

Merchant's invoice number

invoice_deliverymode
optional
Format LIST
Value Comment
M Postal Mail
P PDF (via email)
N no delivery

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

invoice_deliverydate
optional
Format DATE(8), YYYYMMDD

Delivery date (YYYYMMDD)

invoice_deliveryenddate
optional
Format DATE(8), YYYYMMDD

Delivery end date (YYYYMMDD)

invoiceappendix
optional
Format CHAR(1..255)

Dynamic text on the invoice

it[n]
optional
Format List
it[n] Comments
goods Goods
shipment Shipping Charges
handling Handling fee
voucher Voucher / discount

---end

id[n]
optional
Format CHAR(1..32)
Array Array elements [n] starting with [1]; serially numbered; max [400]
Symbols [0-9][a-z][A-Z], .,-,_,/
International Article Number (EAN bzw. GTIN)

Product number, SKU, etc. of this item.

pr[n]
optional
Format NUMERIC(10) max. 19 999 999 99
Array Array elements [n] starting with [1]; serially numbered; max [400]
Unit gross price of the item in smallest unit! e.g. cent.
no[n]
optional
Format NUMERIC(6)
Array Array elements [n] starting with [1]; serially numbered; max [400]

Quantity of this item.

de[n]
optional
Format CHAR(1..255)
Array Array elements [n] starting with [1]; serially numbered; max [400]
Description of this item. Will be printed on documents to customer.
va[n]
optional
Format NUMERIC(4)
Array elements [n] starting with [1]; serially numbered; max [400]

VAT rate (% or bp)

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

sd[n]
optional
Format DATE(8), YYYYMMDD
Array elements [n] starting with [1]; serially numbered; max [400]

Delivery date (YYYYMMDD)

ed[n]
optional
Format DATE(8), YYYYMMDD
Array elements [n] starting with [1]; serially numbered; max [400]

Delivery period end date (YYYYMMDD)

---end

Response Parameters
Permitted Values
APPROVED
PPENDING
ERROR
Response Parameter (approved)
txid
Format NUMERIC(9..12)

The txid specifies the payment process within the PAYONE platform

Response Parameter (approved) - credit card (if AVS has been ordered)
protect_result_avs
Format A..1

AVS return value
 

Response Parameter (Pending)
txid
Format NUMERIC(9..12)

The txid specifies the payment process within the PAYONE platform

Response Parameter (Error)
Format NUMERIC(1..6)

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

Format CHAR(1..1024)

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

Format CHAR(1..1024)

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")

---end

Host: api.pay1.de
    Content-Type: application/x-www-form-urlencoded
    
Payload               
https://api.pay1.de/post-gateway/
add_paydata[cancellation_reason]=undeliverable
amount=1500
currency=EUR
de[1]=Hauptartikel mit Kennzeichnung Versandkostenfrei und Hervorhebung
de[2]=Standard Versand
encoding=UTF-8
id[1]=SW10006
id[2]=Standard Versand
it[1]=goods
it[2]=shipment
key=17031f73e2c6f9755788bddfff04169b
mid=14648
mode=test
no[1]=1
no[2]=1
portalid=2040559
pr[1]=1500
pr[2]=0
request=debit
sequencenumber=2
txid=921178115
va[1]=1900
va[2]=0
RESPONSE
                        
status=APPROVED
txid=921178115
workorderid=PP2ACD85MMXFG7JY
settleaccount=yes