Introduction

Changing the contract data or cancelling a contract.

POST Request - updateaccess
Account Parameters
request
required
Fixed Value: updateaccess
mid
required
your merchant ID, 5-digit numeric
aid
required
your subaccount ID, 5-digit numeric
portalId
required
your Portal ID, 4-digit numeric
key
required
your key value, alpha-numeric
channel
required
Fixed Value: clientapi
channelDetail
required
Permitted Value: payoneHosted
Common Parameters
accessid
required
Format NUMERIC(3..12)

Access ID, defined by PAYONE
action
required
Format LIST
Value Comment
update Update access (default)
cancel Cancel subscription
reverse_cancel Revoke cancellation of sub­scription
lock Block access
unlock Unblock access

Action to perform to given contract
Parameter (update)
clearingtype
optional
Format LIST

Only available with action=update
access_starttime
optional
Format Unixtimestamp

Access starting date as Unixtimestamp
access_expiretime
optional
Format Unixtimestamp

Can be either used with creating a new access (createaccess)
-> Set expiry date/time of the initial term as Unixtimestamp (e.g. date of first renewal)

deprecated, should not be used. Please use “period_unit_trail”, “period_length_trail” instead.
do not use with “period_unit_trail”, “period_length_trail”
or used with updating an existing access (updateaccess)
-> Update expiry date/time of the current term as Unixtimestamp (e.g. overwrite date of next renewal)
productid
optional
Format NUMERIC(1..7)

ID for the offer
amount_trail
optional
Format NUMERIC(1..8), max. value 999 999 99

Total gross amount for initial term. Must equal the sum (quantity x price) of all items for the initial term. 

Required when item is submitted. 

Amount can be "0" (e.g. for test period).
period_unit_trail
optional
Format LIST
Value Comment
Y Value “length” is in years
M Value “length” is in months
D Value “length” is in days

Time unit for initial term

Do not use with “access_expiretime”.

Do not exceed 5 years / 60 months.
period_length_trail
optional
Format NUMERIC(1..4)

Duration of the initial term. Can only be used in combination with period_unit_trail.

Required when period_unit_trail is submitted.

Do not use with “access_expiretime”
amount_recurring
optional
Format NUMERIC(1..8), max. value 999 999 99

Total gross amount of all items of one period during the subsequent term

Must equal the sum (quantity x price) of all items during the subsequent term.

Required when item is submitted.

Amount must not be "0".
period_unit_recurring
optional
Format LIST
Value Comment
Y Value “length” is in years
M Value “length” is in months
D Value “length” is in days
N No subsequent term given

Time unit for subsequent term

Do not exceed 5 years / 60 months.
period_length_recurring
optional
Format NUMERIC(1..4)

Duration of the subsequent term. Can only be used in combination with period_unit_recurring.

Required when period_length_recurring is submitted.
Parameter (update)- module invoicing
id_trail[n]
optional
Format CHAR(1..32)
Array elements [n] starting with [1]; serially numbered; max [100]
Permitted Symbols [0-9][A-Z][a-z][()[]{} +-_#/:]

Product number, order number, etc. of this item (initial term)
no_trail[n]
optional
Format NUMERIC(5)
Array elements [n] starting with [1]; serially numbered; max [100]

Unit gross price of the item (initial term) in smallest unit.
pr_trail[n]
optional
Format NUMERIC(8) max. 999 999 99
Array elements [n] starting with [1]; serially numbered; max [100]

Unit gross price of the item (initial term) in smallest unit.
de_trail[n]
optional
Format CHAR(1..255)
Array elements [n] starting with [1]; serially numbered; max [100]
Example

de[1]=Product 1

de[2]=Product 2

de[3]=Product 3

...

de[100]=Product 100

Description of this item (initial term)
va_trail[n]
optional
Format NUMERIC(8)
Array elements [n] starting with [1]; serially numbered; max [100]

VAT rate (% or bp) (first term)
id_recurring[n]
optional
Format CHAR(1..32)
Array elements [n] starting with [1]; serially numbered; max [100]
Permitted Symbols [0-9][A-Z][a-z][()[]{} +-_#/:]

Product number, order number, etc. of this item (subsequent term)
no_recurring[n]
optional
Format NUMERIC(5)
Array elements [n] starting with [1]; serially numbered; max [100]

Quantity of this item (subsequent term)
pr_recurring[n]
optional
Format NUMERIC(8) max. 999 999 99
Array elements [n] starting with [1]; serially numbered; max [100]

Unit gross price of the item (subsequent term) in smallest unit.
de_recurring[n]
optional
Format CHAR(1..255)
Array elements [n] starting with [1]; serially numbered; max [100]
Example

de[1]=Product 1

de[2]=Product 2

de[3]=Product 3

...

de[100]=Product 100

Description of this item (subsequent term)
va_recurring[n]
optional
Format NUMERIC(4)
Array elements [n] starting with [1]; serially numbered; max [100]

VAT rate (% or bp) (subsequent term)
Parameter (cancel)
access_canceltime
optional
Date of cancellation as Unixtimestamp if cancellation date is in the future, e.g. not until the next period. (After this date no further renewals will be carried out)

(Only possible if the order has not been cancelled already)
Response Parameters
Permitted Values
OK
ERROR
Response parameters (error)
errorcode
Format NUMERIC(1..6)

In case of error the PAYONE Platform returns an error code for your internal usage.
errormessage
Format CHAR(1..1024)

In case of error the PAYONE Platform returns an error message for your internal usage.
customermessage
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")

 
Host: api.pay1.de
Content-Type: application/x-www-form-urlencoded
Payload

accessid=4634635
action=update
aid=52078
api_version=3.11
clearingtype=rec
encoding=UTF-8
key=3adxxxxxxxxxxxxxxxxxxxxxxxx1cb9e
mid=14648
mode=test
portalid=2035
request=updateaccess
RESPONSE

status=OK