Documentation
Documentation
Payment Web Apps BETA

1Introduction to Payment Web Apps

Payment Web Apps allow the integration of payment services that are not directly integrated with our service.

Payment Web Apps generally are just a normal Web Apps with the capability to process payments.

On a high level you have to do the following things to integrate the payment processing with your Web App:

  1. You have to integrate the installation process for you Web App.

  2. You have to use the Payment Web App REST service to add a corresponding processor and one or more connectors.

  3. You have to provide a URL on which you can present a payment page that allows the buyer to confirm the payment.

  4. The buyer confirms the payment on your payment page. You report back via JavaScript the result.

  5. In the background you update the also our backend about the result of the payment processing. For this you are using the update charge attempt operation.

Optionally you can also allow the merchant to do deferred completions and to execute refunds.

The following section will guide through the details about the process to achieve such an integration.

2Installation of the Processor and the Connectors

The processor and the connectors installation works through the Payment Web App REST service. So that you can install them you need first access to the merchant’s space. For this please follow the instructions how the installation of a web app has to be carried out.

Once you have installed the Web App within the merchant’s space the credentials of the Web App allows the installation of the processors and connectors. As part of the installation process you can ask the merchant to grant you certain permissions. To be able afterwards to install the processors and connectors you have to request the Payment Web Apps (ID: 1627022088852) permission.

2.1Inserting a Processor

Once you have requested the permission from the merchant to access the space use the processor insert operation to add a new processor.

As part of the insertion of the processor you have to provide an externalId. This ID has to be unique per space. If the service is invoked with the same externalId multiple times the processor is updated and not a new processor is inserted.

Note
 When the merchant uninstalls your Web App the associated processors will be removed too.

2.2Inserting a Connector

Once you have added a processor you can also insert a connector. To do so you have to use the insert connector operation.

  • externalId: Similar as for the processor you have to provide an externalId. This ID has to be unique. Requests with the same externalId will update the connector and not insert an new one.

  • processorExternalId The connector is always associated with a processor. So you have to provide also the processorExternalId of the previously added processor.

  • completionConfiguration and refundConfiguration: By providing the corresponding configurations you can control whether to support refunds and deferred completions. Keep in mind once you have indicated that you support those optional features you cannot deactivate them anymore on the connector through an update call.

  • paymentPageEndpoint: The paymentPageEndpoint will receive the payment requests. See Payment Page Handling for more details.

  • connector: The connector defines which payment method (and potentially also which brand) is associated with your newly added Web App connector. See below the connectors that you can provide.

See supported connectors for the complete list of supported connectors.

2.3Switch to Live Mode

The processor is by default set automatically ready to be used in the production environment. If you want to first onboard the merchant in a test mode and later switch to a live mode you can do this. When you create a new processor you can define the productionModeUrl. If you provide this URL the user will be forwarded to this URL once the processor is moved to the production mode.

Along the URL the following parameters will be added:

  • timestamp: The time as a unix timestamp (seconds since January 1970). It prevents reply attacks. So you should ensure it is not too old.

  • externalId: The ID of the processor as when created via the web service API. This helps you to identify the processor on your side.

  • returnUrl: When the user has completed the activation you can forward the user back to this URL. Additionally you can append a message and a type. Where the message can contain some message for the user and the type indicates whether it is a failure or success.

  • spaceId: The space ID indicates in which space the processor was installed in.

  • hmac: The HMAC allows to verify if the user really originating from our servers. The calculation of the hmac works in the same way as for other HMACs.

Note
 Please include all parameters you receive on the URL. We might extend the list of parameters in the future. In that case we will include them as well within the HMAC calculation.

3Payment Page Handling

During the installation of the connector you have to provide a payment page endpoint. This endpoint URL will be invoked by the buyer during the payment processing.

This invocation allows to process the payment by asking for further details or to authenticate the buyer etc. The payment page endpoint has to provide the following behavior:

  1. Check the origin of the request. The request contains a HMAC that allows the verification of the origin of the request. So you can be sure that the request is legit.

  2. Ask for further details from the user. For example you ask the user to authenticate them. This step can be also skip when it is not needed.

  3. Once the result of the processing is clear you invoke the corresponding JavaScript to report back the result of the processing of the payment. This feedback is only used within the client. It will trigger in the client the change of the user interface so that user knows the result. In case something goes wrong with the payment and the client crashes you have to report back in the background the result also to our backend.

The following two sections cover the first and last step of the process in more details.

3.1Handle Incoming Payment Page Request

When the buyer invokes the payment page endpoint URL the following parameters will be part of the GET request:

  • transactionId: The transaction ID references the transaction that is currently being processed. In case the merchant allows it there can be multiple charge attempts per transaction.

  • chargeAttemptId: The charge attempt ID references the charge attempt that is carried out as part of this invocation.

  • language: The language indicates the language the buyer is speaking. So the payment page should be rendered in this language. The language parameter is in the format of the IETF language tag. For example de-DE.

  • currency: The currency contains the ISO 3-letter code for the currency (e.g. USD, EUR, CHF etc.).

  • returnUrl: When the payment is completed you have to redirect the user back to this URL.

  • amount: The amount corresponds to the amount that should be charged. The amount format is a normal decimal. For example 10.56. Please keep in mind that you might need to use a dedicated data structure to handle that right. For example in Java you should use a BigDecimal. The number of decimal places depends on the currency.

  • authorizationEnvironment: The environment in which the payment should be carried out. The value can be either TEST or PRODUCTION. In the value is TEST you should just execute a simulated payment. No money should be moved in this case.

  • completionBehavior: The completion behavior indicates whether the payment should be completed IMMEDIATELY or DEFERRED. In case the connector does not support the deferred completion feature the completionBehavior will always be IMMEDIATELY.

  • spaceId: The space ID references the space in which the web app has been installed into.

  • connectorExternalId: This is the ID of the connector that should execute the payment. The ID corresponds to the ID provided during the creation of the connector.

  • merchantReference: The merchant reference helps the merchant to identify the payment. When it makes sense add this reference to the payment. It is not unique but helps normally the buyer and the merchant to understand to which order the payment belongs to.

  • hmac: The hmac contains the hash over the above parameters secured with the Web App secret. The hmac calculation works as other HMACs related to Web Apps. Please include all parameters provided within the HTTP request (excluding already present parameters in the endpoint URL). We might add in the future further parameters and you want to include them otherwise the processing will not work anymore.

If the above parameters do not contain what you need to process the payment you can fetch the transaction object via the REST API. You might need to request more permissions during the installation of the Web App in this case.

The request contains a chargeAttemptId. Each transaction might have multiple charge attempts. Each attempt tries to charge the consumer. If one attempt is successful the transaction is marked as authorized. That implies a transaction can have at most one successful charge attempt. You might want to check that on your side and ensure that this is never an issue. Any subsequent operation (refund, void and completion) will just reference the transaction.

Note
 You have to validate the HMAC to ensure that the system cannot be tampered with. If you miss this an attacker might be able to fake a payment.
Note
 Please include all parameters you receive on the URL. We might extend the list of parameters in the future. In that case we will include them as well within the HMAC calculation.

3.2Update the Charge Attempt

Once you have processed the charge attempt you need to report back to us what the state of the charge attempt is. You have to do this before redirecting the user back to returnUrl. For this purpose you should use charge attempt update REST API operation.

4Deferred Completion

The external service provider can decide to offer also deferred completion. That means that the merchant first authorize an amount and in a second step complete a different amount. To allow such a two step process the connector has to contain the completionConfiguration configuration property. During creation of the connector you can add the corresponding property.

Note
 When the connector has supported once deferred completion it cannot be turned of. So an update that removes the completion configuration will fail.

The completionBehavior parameter within the payment page request indicates whether the payment should be completed directly or if later a completion request will follow. IMMEDIATELY means that the payment has to be booked directly.

4.1Execution of a Completion

When the merchant executes a completion request the completionEndpoint defined within the completionConfiguration will be invoked. The endpoint HTTP POST request contains the following body:

{
	"completionId": 1231231,
	"spaceId": 12,
	"amount": 12.96,
	"transactionId": 542131,
	"merchantReference": "Some reference from the merchant for this completion",
	"lastCompletion": true,
}

Parameter description:

  • completionId: This ID references the completion within our systems. You can use also the web service API to read the completion object with this ID and fetch further details. Together with the spaceId the completionId is unique.

  • spaceId: The space ID references the space to which the completion belongs to.

  • amount: The amount corresponds to the amount that should be completed.

  • transactionId: The ID of the transaction references the transaction object.

  • merchantReference: The merchant reference corresponds to a reference from the merchant to help identifying this completion.

  • lastCompletion: This flag indicates whether this is the last completion of if another completion might follow.

The HTTP request with the above JSON message is repeated until the comopletionEndpoint responds with an HTTP 2xx status code. The feedback about the completion state has to be provided through an invocation of the completion update REST API operation. This feedback has to happen within the completionTimeoutInMinutes. Otherwise we consider the completion as failed.

4.2Execution of a Void

In case the merchant decides not to complete the transaction we execute a void. When the merchant triggered one or more completions no void can be triggered anymore.

When the merchant triggers a void the voidEndpoint defined within the completionConfiguration receives the following HTTP POST request body:

{
	"voidId": 65437,
	"spaceId": 12,
	"transactionId": 542131,
}

Parameter description:

  • voidId: This ID references the void within our systems. You can use also the web service API to read the void object with this ID and fetch further details. Together with the spaceId the voidId is unique.

  • spaceId: The space ID references the space to which the void belongs to.

  • transactionId: The ID of the transaction references the transaction object.

The HTTP request with the above JSON message is repeated until the voidEndpoint responds with an HTTP 2xx status code. The feedback about the void state has to be provided through an invocation of the void update REST API operation. This feedback has to happen within the completionTimeoutInMinutes. Otherwise we consider the void as failed.

5Refunds

Refunds allow a merchant to return money to the buyer. The merchant can trigger such refund only when the connector supports refunds. During the creation of the connector the refundConfiguration property enables refunds for the corresponding connector. When a connector once supported refunds it cannot be turned off. So an update of the connector that does not anymore contain the refundConfiguration will fail.

When the merchant triggers a refund we invoke the refundEndpoint. The HTTP POST request body contains the following JSON:

{
	"refundId": 5623,
	"spaceId": 12,
	"amount": 12.96,
	"merchantReference": "Some reference from the merchant for this refund",
	"transactionId": 542131,
}

Parameter description:

  • refundId: This ID references the refund within our systems. You can use also the web service API to read the refund object with this ID and fetch further details. Together with the spaceId the refundId is unique.

  • spaceId: The space ID references the space to which the refund belongs to.

  • amount: The amount corresponds to the amount that should be refunded to the buyer.

  • transactionId: The ID of the transaction references the transaction object.

  • merchantReference: The merchant reference corresponds to a reference from the merchant to help identifying this refund.

The HTTP request with the above JSON message is repeated until the refundEndpoint responds with an HTTP 2xx status code. The feedback about the refund state has to be provided through an invocation of the refund update REST API operation. This feedback has to happen within the refundTimeoutInMinutes. Otherwise we consider the refund as failed.

6Payment App Connectors

When the payment app is installed you can add the connectors with which you are processing the payments. The following connectors can be used for this.

Id Name
1634723429050 Cryptocurrency