Payment method-specific input parameters (specin.)
Different payment modules require additional information for processing your request. The presence of these extra parameters is also important when determining the actual payment method to use. These method-specific input parameters are documented per payment method in their respective chapters. They are prefixed with “specin.”. You can specify up to 29 specin parameters.
Example for P24:
specin.email: RFC compliant email address of the account holder.
Transient input parameters (transientin.)
These input parameters are payment method-specific and contain transient information (i.e., this information is not persisted by the Payment Gateway) forwarded to the payment method. Example: a list of items purchased by the consumer; URLs to an image of the merchant’s logo, etc.
Example for Klarna:
transientin.orderitems: The purchased items. Passed as URL-encoded serialized JSON string.
Dynamic Descriptor
This parameter is specific to payment and refund methods that support it. Sending the field specin.dynamicdescriptor is optional, and is ignored if not supported. Check the respective payment method documentation to find out whether this feature is supported.
Input parameters for the dynamic descriptor:
| Field | M/O | Type | Description |
|---|---|---|---|
| specin.dynamicdescriptor | O | utf-8 | For a transaction or refund, defines the text on the consumer’s proof of payment (e.g. bank statement record and similar). Typical use cases for this feature: providing (sub-)shop name, a thank you message, product description, etc. See the examples below. |
Depending on the payment or refund method, the actual outcome on the consumer’s statement varies. For example, the set of allowed characters or maximum length can be different. The text resulting from your input value is automatically stripped of whitespace and truncated if it exceeds the maximum length. We may adapt the text if required, for example for reconciliation purposes.
Examples
In the examples below, note how outputs can become truncated, stripped of unsupported characters, and amended with other data needed e.g. for reconciliation (here: 2ABC456).
The output varies depending on the payment method. You can decide to use a shorter descriptor for certain payment methods to avoid truncation.
| specin.dynamicdescriptor | Possible outcomes on statement |
|---|---|
| Example shop thanks you | 2ABC456 Example shop thanks you 2ABC456 EXAMPLESH |
| Example shop, product P | 2ABC456 Example shop, product P 2ABC456 Example shop product P 2ABC456 Example shop prod 2ABC456 EXAMPLESHOPP |
Note
The specin.dynamicdescriptor is an input parameter for the TRANSACTION or the REFUND call.
Payment method-specific output parameters (SPECOUT.)
Different payment methods might provide additional information in the form of specific output parameters. You can find this information in the respective payment method documentation. The specific output parameters are always prefixed “SPECOUT.”.
Well-known SPECOUT parameters
SPECOUT.PAYMENTPURPOSE
Many payment methods provide the specout parameter SPECOUT.PAYMENTPURPOSE.
This parameter reflects what the consumer will see on the proof of payment (e.g. bank statement record and similar). Most payment methods supporting this will report that identifier directly after initializing the transaction, but latest if the transaction reached a SUCCEEDED state (this is also known as the payment descriptor).
SPECOUT.SRC* - Source account information
Some payment methods also provide a set of specout parameters identifying the bank account used by the consumer:
| Parameter | Description |
|---|---|
| SPECOUT.SRCACCOUNTHOLDER | The account holder of the consumer's account. |
| SPECOUT.SRCACCOUNTNUMBER | The account number of the consumer's account. |
| SPECOUT.SRCBANKCODE | The bank code of the consumer's account. |
| SPECOUT.SRCIBAN | The IBAN of the consumer's account. |
| SPECOUT.SRCBIC | The BIC of the consumer's account. |
| SPECOUT.SRCBANKNAME | The bank name of the consumer's account. |
Note
Not all these fields are returned by every payment method since not all information is available every time.
SPECOUT.WAITFORNOTIFICATION
There are payment methods which have a very long PENDING timespan by design. This means that even if the consumer is redirected back to the merchantredirectURL, the transaction will most likely be still in status PENDING for a couple of hours or even days. A notification will be sent once PPRO has a final transaction status available; there's no need to poll PPRO for updates. Wait for the notification about the transaction outcome.
SPECOUT.REDIRECTOPTIONAL
There are payment methods (e.g. SEPA DirectDebit) that allow displaying additional information on a redirection page. You might decide not to redirect the consumer to that URL. In this case the presence of SPECOUT.REDIRECTOPTIONAL (with a value of 1) indicates that a redirect is not required.
Transient output parameters (TRANSIENTOUT.)
Transient output parameters contain payment method-specific information passed from the payment method to you, such as specout parameters. They are not persisted by the Payment Gateway, however, and emitted only in response to the TRANSACTION call.
Subsequent calls to GETTXSTATUS or GETTXSTATUSBYMERCHANTID do not return transient output parameters. You can find information about transient output parameters in the respective payment method documentation. They are always prefixed TRANSIENTOUT..
Accepting unknown output parameters
You are required to accept unknown output parameters. The system will add a random output parameter in response to enforce this policy. This is to ensure that your integration is compliant with this specification and will not break when we release future versions of the API.