PostFinance Card

Home    APMs    PostFinance Card

On this page:
Attributes
  • METHOD TYPECard
  • PAYMENTS
  • PAYOUTS
  • REFUNDS
  • RECURRING

Introduction

PostFinance Card is a prepaid card offered by PostFinance, the banking arm of the Swiss Post Office, that can be used for online and offline purchases.

Supported Countries

  • Switzerland

Supported Currencies

  • EUR
  • CHF

Payment (Deposit) Flow

Press tab to open…

2. Send a /payment Request

Perform the payment by sending a /payment request with its mandatory parameters and include:

  • userTokenId
  • amount
  • currency
  • clientUniqueId
  • paymentOption.alternativePaymentMethod class containing:
    • paymentMethod: “apmgw_PostFinance_Card“
  • deviceDetails class containing: ipAddress
  • billingAddress class containing: firstName, lastName, country, email
  • userDetails class containing: firstName, lastName, country, email
Example /payment Request
{
  "sessionToken":"<sessionToken from /getSessionToken>",
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "amount":"200",
  "currency":"CHF",
  "userTokenId":"<unique customer identifier in merchant system>",
  "clientUniqueId":"<unique transaction ID in merchant system>",
  "paymentOption":{
    "alternativePaymentMethod":{
      "paymentMethod":"apmgw_PostFinance_Card",
      "merchant_unique_id":"<truncated PostFinance Card number>"
    }
  },
  "deviceDetails":{
    "ipAddress":"<customer's IP address>"
  },
  "billingAddress":{
    "firstName": "John",
    "lastName": "Smith",
    "country":"CH",
    "email":"[email protected]"
    },
  "userDetails":{
    "firstName": "John",
    "lastName": "Smith",
    "country":"CH",
    "email":"[email protected]"
  },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction to urlDetails.notificationUrl, which Nuvei recommends including in the /payment request.

Fast Flow (Optional)

To offer customers the option to skip the PostFinance Card payment confirmation page for future payments, include in the checkout() request:

  • savePm: “always“, “true“, or “force” – Fast flow requires a saved payment method. Other possible savePm values do not support fast flow.
  • apmConfig class containing:
    • apmgw_PostFinance_Card class containing:
      • fastFlow: true
  • subMethod: [“ReferenceTransaction”,”AliasRegistration”,”Skrill1Tap”] – Array of submethods that support fast flow.
checkout ({...
    savePm: 'true',
    apmConfig: {
        apmgw_PostFinance_Card: {
            fastFlow: true
        },
    },
    subMethod: ["ReferenceTransaction","AliasRegistration","Skrill1Tap"],...
});

After the transaction is processed, Nuvei sends a DMN that includes the result of the transaction.

REST API
2. Send a /payment Request

Perform the payment by sending a /payment request with its mandatory parameters and include:

  • userTokenId
  • amount
  • currency
  • clientUniqueId
  • paymentOption.alternativePaymentMethod class containing:
    • paymentMethod: “apmgw_PostFinance_Card“
  • deviceDetails class containing: ipAddress
  • billingAddress class containing: firstName, lastName, country, email
  • userDetails class containing: firstName, lastName, country, email
Example /payment Request
{
  "sessionToken":"<sessionToken from /getSessionToken>",
  "merchantId":"<your merchantId>",
  "merchantSiteId":"<your merchantSiteId>",
  "clientRequestId":"<unique request ID in merchant system>",
  "amount":"200",
  "currency":"CHF",
  "userTokenId":"<unique customer identifier in merchant system>",
  "clientUniqueId":"<unique transaction ID in merchant system>",
  "paymentOption":{
    "alternativePaymentMethod":{
      "paymentMethod":"apmgw_PostFinance_Card",
      "merchant_unique_id":"<truncated PostFinance Card number>"
    }
  },
  "deviceDetails":{
    "ipAddress":"<customer's IP address>"
  },
  "billingAddress":{
    "firstName": "John",
    "lastName": "Smith",
    "country":"CH",
    "email":"[email protected]"
    },
  "userDetails":{
    "firstName": "John",
    "lastName": "Smith",
    "country":"CH",
    "email":"[email protected]"
  },
  "timeStamp":"<YYYYMMDDHHmmss>",
  "checksum":"<calculated checksum>"
}

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction to urlDetails.notificationUrl, which Nuvei recommends including in the /payment request.

Simply Connect

Fast Flow (Optional)

To offer customers the option to skip the PostFinance Card payment confirmation page for future payments, include in the checkout() request:

  • savePm: “always“, “true“, or “force” – Fast flow requires a saved payment method. Other possible savePm values do not support fast flow.
  • apmConfig class containing:
    • apmgw_PostFinance_Card class containing:
      • fastFlow: true
  • subMethod: [“ReferenceTransaction”,”AliasRegistration”,”Skrill1Tap”] – Array of submethods that support fast flow.
checkout ({...
    savePm: 'true',
    apmConfig: {
        apmgw_PostFinance_Card: {
            fastFlow: true
        },
    },
    subMethod: ["ReferenceTransaction","AliasRegistration","Skrill1Tap"],...
});

After the transaction is processed, Nuvei sends a DMN that includes the result of the transaction.

Alias Registration

With PostFinance Card’s Alias Registration alternative payment flow, your customers can skip the PostFinance Card payment confirmation page. During a first-time user’s payment (deposit) or registration, you store masked payment data (an Alias) in the customer’s personal profile. Future payments (deposits) using this payment method do not require any further authentication.

Technical Requirements

Transactions over CHF 500 / EUR 350 require a card reader.

In the first /payment request, include in the paymentOption class:

  • subMethod class containing:
    • subMethod: “ReferenceTransaction“
Example First /payment Request
{
    "clientRequestId":"20211203355101",
    "merchantId":"321231666932625700",
    "merchantSiteId":"224668",
    "timeStamp":"20211201155101",
    "checksum":"10F14BF35DC1E16B5A0402D9FD3C008DB47ABA3392B117239AFB08425CA8CCE4",
    "sessionToken":"b0858285-3c2d-4812-b9f4-e6065153246d",
    "userTokenId":"testJohn",
    "clientUniqueId":"Sunisshining444",
    "transactionType":"Sale",
    "paymentOption":{
        "alternativePaymentMethod":{
            "paymentMethod":"apmgw_expresscheckout"
        },
        "userPaymentOptionId": "null",
        "subMethod":{
            "subMethod":"ReferenceTransaction"
        }
    },
    "currency":"CHF",
    "amount":"10",
    "deviceDetails":{
        "ipAddress":"<customer's IP address>"
    },
    "billingAddress":{
        "firstName":"John",
        "lastName":"Smith",
        "email":"[email protected]",
        "phone":"123456789",
        "address":"39 Rotschild st",
        "city":"Geneva",
        "country":"CH"
    },
    "urlDetails":{
        "notificationUrl":"https://cashier.com.e/paymentservice/safecharge/deposit-notification"
    }
}

When this payment is completed, Nuvei receives a response from the APM that includes the Alias and stores it in a userPaymentOptionId. Nuvei includes userPaymentOptionId in the /payment response.

Example First /payment Response
{
    "orderId":"301028008",
    "userTokenId":"testJohn",
    "paymentOption":{
        "redirectUrl":"https://cdn-int.safecharge.com/safecharge_resources/v1/get_to_post/index.html?eyJhbGciOiJSUzI1NiJ9.eyJyZXNwb25zZVVybCI6Imh0dHBzOi8vanVtcGJveC5zYWZlY2hhcmdlLmNvbS9kbXovQXBtQ29ubmVjdG9yL0ZDNjEzN0NGOEY1QTY4NzcyOUIwNzM2QUM2N0MxQTVBIiwiYXV0aGVudGljYXRpb25SZXF1ZXN0IjoiUEQ5NGJXd2dkbVZ5YzJsdmJqMGlNUzR3SWlCbGJtTnZaR2x1WnowaVZWUkdMVGdpSUhOMFlXNWtZV3h2Ym1VOUlubGxjeUkvUGdvOGJuTXdPa0YxZEdobGJuUnBZMkYwYVc5dVVtVnhkV1Z6ZENCdWN6QTZVM0JsWTFabGNuTnBiMjQ5SWpJdU15SWdlRzFzYm5NNmJuTXdQU0pvZEhSd09pOHZaWEJoZVcxbGJuUXVjRzl6ZEdacGJtRnVZMlV1WTJndlpYQmhlVzFsYm5RdmRqSWlQZ29nSUNBZ1BHNXpNRHBTWlhGMVpYTjBTV1ErTWpZeE1EQXdNREF3TURJd09UYzJPVHd2Ym5Nd09sSmxjWFZsYzNSSlpENEtJQ0FnSUR4dWN6QTZRV054ZFdseVpYSkpaRDQwUEM5dWN6QTZRV054ZFdseVpYSkpaRDRLSUNBZ0lEeHVjekE2VUhOd1NXUStNelU4TDI1ek1EcFFjM0JKWkQ0S0lDQWdJRHh1Y3pBNlRXVnlZMmhoYm5SSlpENVFSa0ZSVTBGR1JUQXdNREF3TURFOEwyNXpNRHBOWlhKamFHRnVkRWxrUGdvZ0lDQWdQRzV6TURwUWMzQlFZWGx0Wlc1MFNXUStNall4TURBd01EQXdNREl3T1RjMk9Ud3Zibk13T2xCemNGQmhlVzFsYm5SSlpENEtJQ0FnSUR4dWN6QTZVSFZ5WTJoaGMyVkVZWFJoUGdvZ0lDQWdJQ0FnSUR4dWN6QTZWSEo0Vkhsd1pUNHdQQzl1Y3pBNlZISjRWSGx3WlQ0S0lDQWdJQ0FnSUNBOGJuTXdPbFJ5ZUZScGJXVnpkR0Z0Y0Q0eU1ESTFNREl5T0RFeU5Ea3pNend2Ym5Nd09sUnllRlJwYldWemRHRnRjRDRLSUNBZ0lDQWdJQ0E4Ym5Nd09rRjFkR2h2Y21sellYUnBiMjVCYlc5MWJuUStDaUFnSUNBZ0lDQWdJQ0FnSUR4dWN6QTZRVzF2ZFc1MFBqRXVNRHd2Ym5Nd09rRnRiM1Z1ZEQ0S0lDQWdJQ0FnSUNBZ0lDQWdQRzV6TURwRGRYSnlaVzVqZVQ0M05UWThMMjV6TURwRGRYSnlaVzVqZVQ0S0lDQWdJQ0FnSUNBOEwyNXpNRHBCZFhSb2IzSnBjMkYwYVc5dVFXMXZkVzUwUGdvZ0lDQWdJQ0FnSUR4dWN6QTZUV1Z5WTJoaGJuUlBjbVJsY2tsa1BqaHpaems1T1RsbmMyZHpaMmR6WjNNOEwyNXpNRHBOWlhKamFHRnVkRTl5WkdWeVNXUStDaUFnSUNBOEwyNXpNRHBRZFhKamFHRnpaVVJoZEdFK0NpQWdJQ0E4Ym5Nd09sTmxkSFJwYm1kelBnb2dJQ0FnSUNBZ0lEeHVjekE2UkdsemNHeGhlVXhoYm1kMVlXZGxQbVZ1UEM5dWN6QTZSR2x6Y0d4aGVVeGhibWQxWVdkbFBnb2dJQ0FnSUNBZ0lEeHVjekE2UkdsemNHeGhlVTF2WW1sc1pWTmpjbVZsYmo1bVlXeHpaVHd2Ym5Nd09rUnBjM0JzWVhsTmIySnBiR1ZUWTNKbFpXNCtDaUFnSUNBOEwyNXpNRHBUWlhSMGFXNW5jejRLUEM5dWN6QTZRWFYwYUdWdWRHbGpZWFJwYjI1U1pYRjFaWE4wUGdvPSIsInVybCI6Imh0dHBzOi8vZXBheW1lbnQtaW50LnBvc3RmaW5hbmNlLmNoL3BmY2QvYXV0aGVudGljYXRpb24vdjIifQ.PMmH3LdWqbfomrpbTSpGjhEhaaFeqFDUIMdhqjATe9-zfXjnVJsZt8jkjQNgUut2a5jHVP_E8_6BOS3DUvOmBylLzO114GQofCVuNq8EXe4U192irJgmTnuk-TA5KRUgOOEwsvoPg-KQ3UgaEk3ECUX-PQKYe2N6HA4yaSOteImYDAjmNDTPsp_6hzRUpbKYH5a-v9-se-it4q_psaGeXdWk7UN0480syFbNRwCaGyRLEtXfJgd47trgdRK8ls5bhMnJlYrnttRN9TlHPVUbZMdC2TEDfg7PqS4_54eac2wW3rVd5YGRfZU3t8obNKOmYMTaaJOAAJGZVMnrTJP08g",
        "userPaymentOptionId":"71693528",
        "card":{
            
        }
    },
    "transactionStatus":"REDIRECT",
    "sessionToken":"b0858285-3c2d-4812-b9f4-e6065153246d",
    "clientUniqueId":"Sunisshining444",
    "internalRequestId":342526048,
    "status":"SUCCESS",
    "errCode":0,
    "reason":"",
    "merchantId":"321231666932625700",
    "merchantSiteId":"224668",
    "version":"1.0",
    "clientRequestId":"20211203355101"
}

When you send subsequent transaction requests, include in the paymentOption class:

  • userPaymentOptionId
  • subMethod class containing:
    • subMethod: “ReferenceTransaction“
Example Second /payment Request
{
    "clientRequestId":"20211201155101",
    "merchantId":"321231666932625700",
    "merchantSiteId":"224668",
    "timeStamp":"20211201155101",
    "checksum":"AFC3B55C7A6EC562043599C8C8CAB20AFE97FA282085B7D95C5282877F73853F",
    "sessionToken":"e5d01bad-8c0c-44d5-8821-a0ea78f43153",
    "userTokenId":"testJohn",
    "clientUniqueId":"Sunisshining445",
    "transactionType":"Sale",
    "paymentOption":{
        "userPaymentOptionId":"71693528",
        "subMethod":{
            "subMethod":"ReferenceTransaction"
        }
    },
    "currency":"GBP",
    "amount":"10",
    "deviceDetails":{
        "ipAddress":"<customer's IP address>"
    },
    "billingAddress":{
        "firstName":"John",
        "lastName":"Smith",
        "email":"[email protected]",
        "phone":"123456789",
        "address":"39 Rotschild st",
        "city":"London",
        "country":"GB"
    },
    "urlDetails":{
        "notificationUrl":"https://cashier.com.e/paymentservice/safecharge/deposit-notification"
    }
}
Second Deposit Response Example
{
    "orderId":"301031778",
    "userTokenId":"testJohn",
    "paymentOption":{
        "userPaymentOptionId":"71693528",
        "card":{
            
        }
    },
    "transactionStatus":"APPROVED",
    "transactionId":"711000000003645919",
    "sessionToken":"e5d01bad-8c0c-44d5-8821-a0ea78f43153",
    "clientUniqueId":"Sunisshining445",
    "internalRequestId":342540878,
    "status":"SUCCESS",
    "errCode":0,
    "reason":"",
    "merchantId":"321231666932625700",
    "merchantSiteId":"224668",
    "version":"1.0",
    "clientRequestId":"20211201155101"
}

User Experience

Payment

The user is redirected to the PostFinance Card website.

The transaction amount determines the specific experience.

Transaction Amount < CHF 500 / EUR 350

The user enters an ID number and the card number.

Transaction Amount > CHF 500 / EUR 350

The user enters an ID number and the code from the card reader.

Last update iconLast modified April 2025