> For the complete documentation index, see [llms.txt](https://docs.saferpay.com/home/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.saferpay.com/home/integration-guide/payment-methods/swiss-postcard-and-postfinance.md).
# PostFinance Pay
Via the Saferpay JSON API, payments can be handled through PostFinance Pay.
## General requirements
Acceptance of PostFinance Pay requires:
* A [corresponding license](/home/master/licensing.md) and thus a valid identification with a username and password for the Saferpay system.
* A valid contract with PostFinance.
### Technical requirements
The general integration of PostFinance Pay can be done via the [Payment Page](/home/integration-guide/licences-and-interfaces/payment-page.md) and has the following requirements for integration:
* JSON API Version 1.37 or later.
* [Recurring payments](/home/integration-guide/licences-and-interfaces/transaction-interface/recurring-payments.md) are only available [via Alias](/home/integration-guide/licences-and-interfaces/transaction-interface/recurring-payments.md#recurring-payments-using-an-alias).
* Postfinance Pay does not support the [Iframe integration](/home/integration-guide/general-information/iframe-integration-and-css.md#iframe-integration). [Saferpay will break out of the IFrame, if necessary](/home/integration-guide/general-information/iframe-integration-and-css.md#iframe-support).
* The **`Payment.OrderId`** is restricted to a maximum of 18 characters. Anything more will be truncated.
{% hint style="warning" %}
PostFinance Pay transactions are only valid for 30 days and must be [captured](/home/integration-guide/licences-and-interfaces/capture-and-daily-closing.md) in this time frame. After 30 days, the reservation will void and the authorized amount can no longer be transferred! However you have a guaranteed payout, within these 30 days.
{% endhint %}
{% hint style="warning" %}
[Refunds](/home/integration-guide/licences-and-interfaces/transaction-interface/refunds.md) may only be executed up to 12 months, after the original transaction.
{% endhint %}
### Supported features
| Feature | Support |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------: |
| [Capture](/home/integration-guide/licences-and-interfaces/capture-and-daily-closing.md)/[Cancel](/home/integration-guide/licences-and-interfaces/capture-and-daily-closing.md#cancel) | ✅ / ✅ |
| [Multipart Captures](/home/integration-guide/licences-and-interfaces/capture-and-daily-closing/partial-captures.md) | ✅ |
| [Secure Card Data](/home/integration-guide/licences-and-interfaces/secure-card-data.md) | ✅ |
| [Refunds](/home/integration-guide/licences-and-interfaces/transaction-interface/refunds.md) | ✅ |
| [Recurring Payments](/home/integration-guide/licences-and-interfaces/transaction-interface/recurring-payments.md) | ✅
Needs attention!
|
| 3D Secure | ❌ |
| Dynamic Currency Conversion (DCC) | ❌ |
| Mail Phone Order | ❌ |
| [Testing](#testing) | ✅ |
| Omni-Channel | ❌ |
## Storage in the Secure Card Data Store
If you intend on saving PostFinance Pay-data for later use, Saferpay provides the possibility of storing the payment data inside the Saferpay Secure Card store, for the [Payment Page ](/home/integration-guide/licences-and-interfaces/secure-card-data.md#secure-card-data-and-the-payment-page)and the [Standalone Alias Registration](#stansdalone-registration). For this, the following requirements must be met:
* Activation of Saferpay Secure Card Data in the Saferpay merchant account.
* The feature must also be activated on PostFinance side.
### Standalone registration
If you intend to use the [standalone registration](/home/integration-guide/licences-and-interfaces/secure-card-data.md#standalone-secure-card-data-registration), you need to specify the parameter **Type** with the value **POSTFINANCEPAY**, which signals that you want to save Postfinance Pay payment means.
{% tabs %}
{% tab title="Request" %}
```json
{
"RegisterAlias": {
"IdGenerator": "RANDOM_UNIQUE"
},
"Type": "POSTFINANCEPAY",
"LanguageCode": "en",
"RequestHeader": {
"SpecVersion": "1.37",
"CustomerId": "242225",
"RequestId": "5f543be575b3f3ecff3214257ac6978a",
"RetryIndicator": 0,
"ClientInfo": {
"ShopInfo": "My Shop",
"OsInfo": "Windows Server 2013"
}
},
"ReturnUrl": {
"Url": "https://www.myshop.com/"
}
}
```
{% endtab %}
{% endtabs %}
## Address collection from PostFinance
This function is currently not yet available and will be delivered at a later date.
## Instant Payouts
Instant Payouts enables merchants to directly fund Swiss bank accounts. Use-cases may include the payout of winnings and other cases, that do not directly refund a previously made transaction.
### Requirements
Instant Payouts requires the following things in order to work:
* The merchant needs a dedicated Instant Payout contract and a bank account with PostFinance.
* Activation of said contract on the desired Saferpay Terminal-ID
* The recipient needs a bank account with a participating Swiss bank.
* **API SpecVersion** 1.50+
{% hint style="info" %}
Instant payouts are only possible in Swiss francs and up to a maximum amount of CHF 20'000. If the PostFinance recipient account is held in a foreign currency, PostFinance will convert the amount.
{% endhint %}
### Technical Integration
From a technical standpoint, the merchant is performing a [**RefundDirect request**](https://saferpay.github.io/jsonapi/#Payment_v1_Transaction_RefundDirect), with which they are providing the IBAN of the destination bank account, inside the **`PaymentMeans.BankAccount`** container.
In addition, for legal reasons, you **must** also send the **complete address** of the recipient inside the **`OriginalCreditTransfer.Recipient`** container. Not submitting the address may lead to errors, or rejections.
#### Example
```json
{
"RequestHeader": {
"SpecVersion": "[current Spec-Version]",
"CustomerId": "[your customer id]",
"RequestId": "[your request id]",
"RetryIndicator": 0
},
"TerminalId": "[your terminal id]",
"Refund": {
"Amount": {
"Value": "100",
"CurrencyCode": "CHF"
}
},
"PaymentMeans": {
"BankAccount": {
"IBAN": "CH98123456789012345",
"HolderName": "John Doe"
}
},
"OriginalCreditTransfer": {
"Recipient": {
"FirstName": "John",
"LastName": "Doe",
"Gender": "MALE",
"Email": "john.doe@provider.com",
"CountryCode": "ch",
"City": "Somecity",
"Street": "Somestreet 1",
"Zip": "12345",
"Phone": "+411234567890123",
"DateOfBirth": "1989-03-17"
}
}
}
```
### Pending refund capture
Under certain circumstances, Saferpay cannot retrieve the information about an Instant Payout refund capture in time to respond with either a success or a failure, due to processing limitations on the banking side. In this case, you will receive a [Capture](/home/integration-guide/licences-and-interfaces/capture-and-daily-closing.md) **`"Status": "PENDING"`**.
In this state, the success or failure of the capture is still open and will change in the future.
Saferpay can notify you about a status change if you set an e-mail inside the [Settings > Notification > Pending status](/home/interfaces/backoffice/settings.md#pending-status) section of the Backoffice.
### Handling pending captures on API level
The whole **`PENDING`** procedure can be handled automatically via API, so that your system can automatically adjust the transaction status once the final [Capture](/home/integration-guide/licences-and-interfaces/capture-and-daily-closing.md) state has been confirmed.
First, you have to set the **`PendingNotification`** container with the [Capture request](/home/integration-guide/licences-and-interfaces/capture-and-daily-closing.md). This container behaves basically the same as the [normal Payment Page flow](/home/integration-guide/licences-and-interfaces/payment-page.md):
* **`MerchantEmails`:** This array can store up to 10 different emails, to which Saferpay will send an email once the final [Capture](/home/integration-guide/licences-and-interfaces/capture-and-daily-closing.md) status has been confirmed, informing a person or team directly.
* **`NotifyUrl`**: This URL is the important part for automatic processing. It behaves similarly to the NotificationUrls you know from the Payment Page itself. It will be called once Saferpay has been able to confirm the final [Capture](/home/integration-guide/licences-and-interfaces/capture-and-daily-closing.md) status.
Once the **`NotifyUrl`** has been called, you can query the final outcome of the [Capture](/home/integration-guide/licences-and-interfaces/capture-and-daily-closing.md) by using the [Assert Capture request](https://saferpay.github.io/jsonapi/#Payment_v1_Transaction_AssertCapture), allowing you to update the refund transaction on your system automatically.
#### What if the Capture returns a failure?
This is a possible scenario and should this happen, it is best to [cancel the whole refund](/home/integration-guide/licences-and-interfaces/capture-and-daily-closing.md#cancel) and execute a new one.
## Testing
Please refer to [this chapter](https://docs.saferpay.com/home/integration-guide/testing-and-go-live#postfinance-pay), if you want to test PostFinance Pay.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.saferpay.com/home/integration-guide/payment-methods/swiss-postcard-and-postfinance.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.