Page tree
Skip to end of metadata
Go to start of metadata

 Additional specification

Currently there are some technical limitations regarding the “fulfillment_delay” and “refund_announcement”. If you plan on using them you have to implement the the “preauthorization” instead of “authorization”also always use API version 3.10 when using Paysafe Pay Later™.

Referencing preliminary requests by “workorderid”

Paysafe Pay Later™ offers a couple of preliminary requests (“calculation” and “pre_check”) that need to be referenced during the preauthorization/auothorization of a transaction.

The “pre_check” request can be used to perform a preliminary risk check. This request is optional.

The “calculation” request is required for installment transactions.

If you decide to use the pre_check in your implementation, make sure that you pass the workorderid returned by the “pre_check” on to following requests.

Example:

  • If you try to perform an installment payment with a preceding “pre_check” you need to reference the “pre_check”’s workorderid in both the “calculation” and “preauthorization”/”authorization” requests. In this particular case, you don’t need to reference the workorderid of the “calculation” request.

  • If you try to perform an installment payment without a preceding “pre_check” you need to reference the workorderid of the preceding “calculation” request.

  • If you try to perform an invoice payment with a preceding “pre_check” you need to reference the workorderid of the “pre_check”

Fraud Prevention

Paysafe offers the possibility to send a session_id, referencing a complete customer session. This is to make sure, that all requests sent by the merchant, belong to the same customer session. This helps paysafe to make sure, that there are no fraudulent requests sent by a third party.

For each checkout process, a session ID has to be created and transmitted to paysafe in two ways:

1. When loading the fraud prevention JS, and 2. during API requests.


The add_paydata[analysis_session_id] is a temporary identifier that is unique to the visitor’s session and per event/order. It can be up to 128 bytes long and must only consist of the following characters:

  • upper and lowercase English letters([az], [A-Z])
  • digits (0-9)
  • underscore (_)
  • hyphen(-)
Example
SessionId= merchantshop_cd-695a7565-979b-4af9

Recommendations for creation of add_paydata[analysis_session_id]:

  • Use a merchant identifier (URL without domain additions), append an existing session identifier from a cookie, append the date and time in milliseconds to the end of the identifier and then applying a hexadecimal hash to the concatenated value to produce a completely unique Session ID.
  • Use a merchant identifier (URL without domain additions), append an existing session identifier from the web application and applying a hexadecimal hash to the value to obfuscate the identifier.

Define a session ID. Paysafe recommends to concatenate the merchant name, an existing session identifier and a timestamp in milliseconds, then apply a hexadecimal hash function. The session ID must be retained through the checkout process.

Load the fraud prevention JavaScript, be sure to replace the [SessionID] placeholder. 363t8kgq is a static value:

<head>
     <script type="text/javascript" src="https://h.online-metrix.net/fp/tags.js?org_id=363t8kgq&session_id=[SessionID]"></script>
</head>
  
<body>
     <noscript>
          <iframe style="width: 100px; height: 100px; border: 0; position: absolute; top: -5000px;" src="https://h.online-metrix.net/fp/tags?org_id=363t8kgq&session_id=[SessionID]"></iframe>
     </noscript>
</body>

You are free to use any asynchronous loading mechanism. We strongly recommend to load the JS only when the customer hits the acceptance checkbox of the privacy statement to avoid GDPR issues.

The session ID must be added to all pre_check and authorization/preauthorization requests in the paramter add_paydata[analysis_session_id]


B2B Transactions

Paysafe Pay Later™ supports B2B transactions for (monthly) Invoice and Debit transactions. If you want your transaction to be flagged as B2B, you need to set the parameter “add_paydata[b2b]” to “yes” for all requests regarding this transaction.

B2B transactions are only available for Paysafe Pay Later™ Invoicing.

Paysafe Pay Later™ HTTP Authentication

As part of the calculation request response a document URL is returned as well (StandardCreditInformationUrl). In order to access the referenced document HTTP authentication is required. The user credentials are the channelname and password provided by Paysafe Pay Later™.

Preauthorization/Authorization

Request

Parameter

Required

Comment

api_version+Has to be "3.10"

clearingtype

+

Has to be "fnc": Financing

financingtype

+

PYV: Paysafe Pay Later™-Invoicing

PYM: Paysafe Pay Later™-Monthly

PYS: Paysafe Pay Later™-Installment

PYD: Paysafe Pay Later™-Debit

amount

+

Total amount (in smallest currency unit! e.g. cent)

currency

+

Currency (ISO 4217)

Specifies currency for this transaction


Format

LIST 

Permitted values

 ISO 4217 (currencies) 3-letter-codes

Samples

EUR
USD
GBP

workorderid

o

Required for Preauth/Auth of Paysafe Pay Later™-Installment / references the preceding calculation request

The workorderid is a technical id returned from the PAYONE platform to identify a workorder. A workorder is a part of a payment process (identified by a txid). The workorderid is used for the genericpayment request.

Format

CHAR(1..50)

narrative_text

-

Dynamic text element on account statements

Format

CHAR(1..81)

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

reference

+

Merchant reference number for the payment process

Merchant reference number for the payment process (case insensitive)

Format

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

email

+

Customers e-mail address

email-address of customer

Format

CHAR(5..254)
Permitted Symbols
RFC 5322

it[n]

-

it[n]

Comments

goods

Goods

shipment

Shipping Charges

Note: handling and voucher are not supported and will be mapped to goods

id[n]

-

International Article Number (EAN bzw. GTIN)

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]

-

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]

-

Quantity of this item

Format

NUMERIC(6)

Array

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

de[n]

-

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

add_paydata[installment_duration]

o

Required for Paysafe Pay Later™-Installment, value has to be the result of a preceding generic calculation request

company

o

Company name, required for B2B transactions (if add_paydata[b2b] = “yes”)

birthday+

Date of birth of customer


Format

DATE(8), YYYYMMDD

Samples

20190101
19991231

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)

street

+

Street number and name

zip

+

Postcode

Format

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

city

+

City

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"

ip

+

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

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)

iban - definition

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)
Permitted Symbols
[0-9][A-Z]

add_paydata[company_trade_registry_number]

-

Trade registry number for B2B transactions

add_paydata[b2b]

-

Optional, defaults to “no”

Set “yes” for B2B transactions

B2B transactions only available for PYV transactions.

For additional information refer to chapter 1.4

add_paydata[company_uid]

-

VAT identification number, recommended for better acceptance rates with b2b transactions

add_paydata[company_register_key]

-

ID of other company register than trade registry or UID

add_paydata[mobile]

-

Optional mobile phone number

add_paydata[analysis_transportation_<suffix>]

-

<suffix> is one of:

company - DHL, UPS

tracking - delivery tracking package id

return_tracking - for tracking id of returns

You can use these parameters on authorization and capture requests

add_paydata[analysis_customer_<suffix>]

-

<suffix> is one of:

group - customer group

confirmed_orders - recently confirmed orders

confirmed_amount - recently confirmed amount

internal_score - internal risk score of the merchant

add_paydata[analysis_item_category_<n>]

-

Item category

Replace <n> with the shopping item id you want to categorize

add_paydata[analysis_webshop_url]

-

Webshop URL

add_paydata[payolution_session_id]-see Chapter "Fraud Prevention" for more details

 Response

Parameter

Required

Comment

workorderid

-

Used to reference a preceding calculation or pre-check request

status

+

APPROVED / REDIRECT / ERROR / PENDING

txid

+

Transaction ID

add_paydata[clearing_reference]

+

accounting number, used to print on the invoice

Parameter (ERROR)

errorcode

+

Error number

errormessage

-

Error message

customermessage

-

Error message for the end customer

(Language selection is based on the end customer’s language, „language“)

Capture

The capture request is used to finalize a preauthorized transaction.

If you use preauth/Capture with installment transactions, the capture request has to be sent right after the preauthorization

Request


Parameter

Required

Comment

txid

+

Payment process ID (PAYONE)

clearingtype

+

Has to be "fnc": Financing

financingtype

+

PYV: Paysafe Pay Later™-Invoicing

PYM: Paysafe Pay Later™-Monthly

PYS: Paysafe Pay Later™-Installment

PYD: Paysafe Pay Later™-Debit

add_paydata[b2b]

-

Optional, defaults to “no”

Set “yes” for B2B transactions

B2B transactions only available for PYV transactions.

For additional information refer to chapter 1.4

capturemode

+

Specifies whether this capture is the last one or whether there will be another one in future.

Format

LIST 
ValueComment
completed
  • Set with last capture; i.e.: Delivery completed.
  • No further capture is allowed.
notcompleted
  • Set with partial deliveries (last delivery with "completed")
  • Another capture is expected to complete the transaction.

Payment specific:

Payment typeComment

PDT

Parameter "capturemode" is mandatory.
KLS, KLVParameter "capturemode" is mandatory.

amount

+

Amount to be entered (in smallest currency unit! e.g. cent)

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

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

currency

+

Specifies currency for this transaction


Format

LIST 

Permitted values

 ISO 4217 (currencies) 3-letter-codes

Samples

EUR
USD
GBP

narrative_text

-

Human readable description of the reason for the transaction

add_paydata[analysis_customer_<suffix>]

-

<suffix> is one of:

group - customer group

confirmed_orders - recently confirmed orders

confirmed_amount - recently confirmed amount

internal_score - internal risk score of the merchant

add_paydata[analysis_invoice_id]

-

Additional field for an invoice ID that the merchant can use for his own purposes

add_paydata[analysis_order_id]

-

Additional field for an order ID that the merchant can use for his own purposes

 Response


Parameter

Required

Comment

status

+

APPROVED / ERROR

txid

+

Payment process ID (PAYONE)

add_paydata[clearing_reference]

+

accounting number, used to print on the invoice (only for API version >3.10)

Debit/Refund

Only Paysafe Pay Later™specific parameters are described here. Refer to the Payone API description

Request


Parameter

Required

Comment

add_paydata[analysis_invoice_id]

-

Additional field for an invoice ID that the merchant can use for his own purposes

add_paydata[analysis_order_id]

-

Additional field for an order ID that the merchant can use for his own purposes

add_paydata[b2b]

o

Optional, defaults to “no”

Set “yes” for B2B transactions

B2B transactions only available for PYV transactions.

For additional information refer to chapter 1.4


genericpayment – add_paydata[action] = calculation

The calculation request is used, whenever you need to retrieve financing plans for the payment type “Paysafe Pay Later™-Installment”. It accepts the amount of the transaction as an input parameter and returns all possible payment plans.

The calculation request has to be referenced in an installment preauthorization/authorization. add_paydata[installment_duration] is used to specify the desired duration for the payment plan in months.

Request

Parameter

Required

Comment

add_paydata[action]

+

For “calculation” Requests this has to be:

-          calculation

clearingtype

+

Has to be "fnc": Financing

financingtype

+

PYV: Paysafe Pay Later™-Invoicing

PYM: Paysafe Pay Later™-Monthly

PYS: Paysafe Pay Later™-Installment

PYD: Paysafe Pay Later™-Debit

amount

o

Required for action=pre_check and action=calculation

currency

+

Specifies currency for this transaction


Format

LIST 

Permitted values

 ISO 4217 (currencies) 3-letter-codes

Samples

EUR
USD
GBP

add_paydata[analysis_merchant_comment]

-

Comment field for the merchant

add_paydata[company_uid]

-

Only for action=pre_check

VAT identification number, recommended for better acceptance rates with b2b transactions

 Response


Parameter

Required

Comment

status

+

OK / ERROR

workorderid

+

The workorderid has to be referenced during preauth/auth

add_paydata[PaymentDetails _<n>_Currency ]

-

Currency

 

add_paydata[PaymentDetails_<n>_StandardCreditInformationUrl ]

-

A URL to the EU Standard Credit Information hosted by payolution

add_paydata[PaymentDetails_<n>_Usage ]

-

A human readable description of the reason for the payment

Replace n with natural number

add_paydata[PaymentDetails_<n>_Duration]

-

Defines how many installments are used to perform the payment

Replace n with natural number

add_paydata[PaymentDetails_<n>_EffectiveInterestRate]

-

The effective interest rate p.a. in percent

add_paydata[PaymentDetails_<n>_InterestRate]

-

The interest rate p.a. in percent

add_paydata[PaymentDetails_<n>_MinimumInstallmentFee ]

-

The minimum fee for the installment payment, which will be charged even if the interest would be lower than that (e.g. because of partial refunds)

add_paydata[PaymentDetails_<n>_OriginalAmount]

-

The original transaction amount as transmitted by the merchant

add_paydata[PaymentDetails_<n>_TotalAmount]

-

The total transaction amount as transmitted by the merchant

add_paydata[PaymentDetails_<n>_Installment_<m>_amount]

-

Amount of installment number m

add_paydata[PaymentDetails_<n>_Installment_<m>_due]

-

Due date of installment number m

add_paydata[PaymentDetails_<n>_Installment_<m>_dueInDays]

-

Number of days until installment number m is due

genericpayment – add_paydata[action] = pre_check

This can be used to perform a preliminary risk check.

Request

Parameter

Required

Comment

clearingtype

+

Has to be "fnc": Financing

financingtype

+

PYV: Paysafe Pay Later™-Invoicing

PYM: Paysafe Pay Later™-Monthly

PYS: Paysafe Pay Later™-Installment

PYD: Paysafe Pay Later™-Debit

ip

+

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

email

+

Customers e-mail address

add_paydata[action]

+

For “pre-check” Requests this has to be:

-          pre_check

add_paydata[payment_type]

+

Format

LIST 

Permitted values

Payolution-Invoicing
Payolution-Installment
Payolution-Monthly
Payolution-Debit

add_paydata[b2b]

-

Optional, defaults to “no”

Set “yes” for B2B transactions

B2B transactions only available for PYV transactions.

For additional information refer to chapter 1.4

add_paydata[company_trade_registry_number]

-

Trade registry number for B2B transactions

add_paydata[company_register_key]

-

ID of other company register than trade registry or UID

add_paydata[mobile]

-

Only for action=pre_check

Optional mobile phone number

amount

+

Amount to be entered (in smallest currency unit! e.g. cent)

currency

+

Specifies currency for this transaction


Format

LIST 

Permitted values

 ISO 4217 (currencies) 3-letter-codes

Samples

EUR
USD
GBP

company

o

Company name, required for B2B transactions (if add_paydata[b2b] = “yes”)

birthday

+

Date of birth (YYYYMMDD)

firstname

+

First name

lastname

+

Surname

street

+

Street number and name

zip

+

Postcode

city

+

City

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"

add_paydata[payolution_session_id]-see Chapter "Fraud Prevention" for more details

Response 

Parameter

Required

Comment

status

+

OK / ERROR

workorderid

+

The workorderid is a technical id returned from the PAYONE platform to identify a workorder. A workorder is a part of a payment process (identified by a txid). The workorderid is used for the genericpayment request.

Format

CHAR(1..50)

 

genericpayment – add_paydata[action] = refund_announcement

If a customer announces a return to the customer support it is possible to send a “refund_announcement” request in order to stop the dunning process.

Request

Parameter

Required

Comment

add_paydata[action]

+

For “refund_announcement” Requests this has to be:

-          refund_announcement

clearingtype

+

Has to be "fnc": Financing

financingtype

+

PYV: Paysafe Pay Later™-Invoicing

PYM: Paysafe Pay Later™-Monthly

PYS: Paysafe Pay Later™-Installment

PYD: Paysafe Pay Later™-Debit

add_paydata[txid]

+

Not the regular TXID that is returned by all preauth/auth requests. This txid is returned as “add_paydata[txid]” for preauthorizations using API version 3.10

workorderid

+

The “workorderid” of the corresponding preauth/auth request. It is only returned for preauthorizations using API version 3.10

amount

+

Amount to be entered (in smallest currency unit! e.g. cent)

currency

+

Specifies currency for this transaction


Format

LIST 

Permitted values

 ISO 4217 (currencies) 3-letter-codes

Samples

EUR
USD
GBP

Response

Parameter

Required

Comment

status

+

OK / ERROR

workorderid

+

The workorderid is a technical id returned from the PAYONE platform to identify a workorder. A workorder is a part of a payment process (identified by a txid). The workorderid is used for the genericpayment request.

Format

CHAR(1..50)

genericpayment – add_paydata[action] = fulfillment_delay

If the merchant can’t abide by his commited fulfillment date, it is possible to send a “fulfillment_delay” request in order to delay the dunning process until a specified date.

Request

Parameter

Required

Comment

add_paydata[action]

+

For “fulfillment_delay” requests this has to be:

-          fulfillment_delay

add_paydata[analysis_expected_fulfillment_date]

+

New expected fulfillment date.

Format: YYYY-MM-DD

add_paydata[txid]

+

Not the regular TXID that is returned by all preauth/auth requests. This txid is returned as “add_paydata[txid]” for preauthorizations using API version 3.10

workorderid

+

The “workorderid” of the corresponding preauth/auth request. It is only returned for preauthorizations using API version 3.10

amount

+

Amount to be entered (in smallest currency unit! e.g. cent)

currency

+

Specifies currency for this transaction


Format

LIST 

Permitted values

 ISO 4217 (currencies) 3-letter-codes

Samples

EUR
USD
GBP

Response

Parameter

Required

Comment

status

+

OK / ERROR

workorderid

+

The workorderid is a technical id returned from the PAYONE platform to identify a workorder. A workorder is a part of a payment process (identified by a txid). The workorderid is used for the genericpayment request.

Format

CHAR(1..50)

Sequence Diagrams

Installment Authorization and Refund

Installment Preauthorization and Refund

Invoice Sale Authorization and Refund

Invoice Preauthorization and Refund

 

Reversal


  • No labels