Payments

To use linkID payments, the process is similar to a normal authentication. A payment context is piggybacked in the SAML v2.0 authentication request you send out. Check out the server side document of the Java SDK or the .NET SDK to know how.

Payment context

In the payment context, you can specify the following:

• Amount amount to pay, expressed in cents so amount of 100 == 1 EUR
• Currency currency to pay in, only EUR is supported for now
• Payment description linkID will allways first show a default, non modifiable payment description in the mobile app. This to ensure that the web application cannot by accident show a wrong payment amount to the user. The optional payment description can be used to add some extra meaningful context to the payment transaction. This is optional.
• Order reference An order reference which will be used in payment status updates sent from linkID to your webapp. This is optional, if not specified linkID will generate a UUID one for you. The order reference is returned in the PaymentResponse piggybacked on the returned SAML v2.0 authentication response
• Payment profile within the payment configuration in linkID and DocData for your application, you can define multiple payment profiles. These allow for specifying that for example for a certain transaction only credit cards are allowed to be used. This is optional, a default will be configured when setting up your app within the linkID backend.
• Payment validation time payment validation time is the time linkID will wait for validation of the payment transaction.

Payments for users with no payment method linked

If a linkID user wants to make a linkID payment, but has not yet linked a payment method to his linkID account, you have the following options:

1. Deferred payments: Here the linkID user will be sent an e-mail with a link where he can complete the payment at a later time. This way the user can make the payment and simultaneously add a payment method to his linkID account at later time. The linkID payment will finish and the payment response embedded in the SAML v2.0 authentication response will have a payment state DEFERRED. To enable this, set the allowDeferredPay in the PaymentContext you pass to linkID.

2. Add the payment method in the client: This if this is enabled for the specific payment method type. You do not have to do anything here, the linkID backend configuration for your application/payment merchant will do everything.

3. Add the payment method in the browser: If enabled, the linkID client will show a continue in browser button. When the user selects this, linkID will return a paymentMenuURL in the PaymentResponse in the AuthenticationResponse. It is then your webapp's responsibility to redirect the user to this URL to finalize the payment. To enabled this, set the PaymentAddBrowser variable in the PaymentContext you pass to linkID to REDIRECT. The alternative is to just disable this option.

Payment validation time

Depending on the type of payment method, validation of the payment transaction can take more time than you want. Depending on your needs you can optionally make linkID wait a bit longer or not wait at all. By default linkID waits 5 seconds.

Either way, when linkID receives a notification that the payment transaction has been validated, it can inform your webapp of this. For this we will need to know where we can do this. Consult a linkID guy to configure this for your app.

We will notify you via a simple HTTP GET as follows

https://your.host.com/site/paymentUpdate?orderRef=132456-78996-4563-45636

You then need to request detailed payment information for that transaction using the linkID payment web service.

Check out following examples for more detail:

• Java example
• .NET example
• PHP example