Giropay

The Paysafe Payments API supports Giropay as a payment instrument. Giropay is a German payment method based on online banking. Giropay allows its customers to complete transactions online using their online banking environment, where funds are debited from their bank account and deposited directly to your account or a wallet setup at your end.

Depending on their bank, customers confirm payments on Giropay using a second factor of authentication or a PIN. Giropay redirects customers to their website to authenticate the payment and there is an immediate confirmation to the customer and you about the success or failure of a payment.

Features

Supported region: Germany.
Supported currency: EURO.
Giropay accounts for 10% of online checkouts in Germany.
Immediate confirmation to the customer about the success or failure of a payment.

Setup Requirements

For Paysafe to create a test account in the sandbox and production environment, we need the following details.

You must be onboarded with Skrill's solution.
Your Skrill Pay to Email
Your Skrill account API/MQI Password
Website Id

Transaction types

We support the following transaction types

Payments
Refunds
Standalone Credits

Click on the video to see how Giropay works.

Typical Scenarios

Giropay Payment

To process a payment request using Giropay:

Create a payment handle with the following parameter settings:
transactionType: PAYMENT
paymentType: GIROPAY
Pass the following parameters in the GIROPAY object:
consumerId: email ID of the consumer.
countryCode: Two-digit unique country code to identify the area of operation of bank account and currency.
websiteId: Unique Merchant ID created at Skrill to identify you.
Consumer needs to complete the payment by selecting a bank account on Giropay page, Paysafe returns a response with the following:
- The action parameter set to REDIRECT
- A payment redirect link pointing to Giropay page URL
- The status of the payment handle set to INITIATED.
Consumer must provide these details – First Name, Last Name, and Email ID.
Consumer selects the bank on Giropay page and logs in to finish the transaction.
The consumer is navigated to a success or failed page depending on the status of the transaction.
- If the transaction is successful, the payment handle's status changes to PAYABLE.
- If the transaction is unsuccessful, the payment handle's status changes to FAILED.
- A webhook will let you know about the status change.
Use the paymentHandleToken returned in the response to process the payment request.

The paymentId returned in the response should be stored at your end for future use, since paymentId is needed for both refunds and withdrawals to directly deposit into the bank account that was used for the original transaction.

APIs to use

Payment Handles Payments

Auto-Settlement and Auto-Refund

If you did not make a Payments API call and opted for auto-settlement and auto-refund, then you can process payments and settlements:

Auto-settlement: After 15 minutes, the system will automatically trigger the Payments API call and finish the payments and settlements. The payment handle also gets expired.
Auto-settlement and Auto-refund: After 15 minutes, the system will automatically trigger the Payments API call and finish the payments, settlements, and refunds. The payment handle also gets expired.

To opt for this functionality, email Integrations team(integrations@paysafe.com).

Giropay Withdrawal/Standalone Credits

To process a withdrawal payment request using Giropay as the payment type:

Create a Payment Handle with the following parameter settings:
transactionType: STANDALONE_CREDIT
paymentType: GIROPAY
Pass the following parameters in the GIROPAY object:
- paymentId: This is the ID of the payment done previously, from which the bank details would be extracted, and the withdrawal money would be transferred to without asking the customer to enter details again. This is used to prevent fraudulent transactions, as only accounts which are used in deposit should be used for withdrawals.
- emailSubject: Customizable subject of the email that would be triggered to the customer, informing them about the details of the transaction.
- emailMessage: Customizable body of the email that would be triggered to the customer, informing them about the details of the transaction.
- consumerId: email ID of the consumer.
In response, a one-time token would be received with the tag paymentHandleToken and the status would be PAYABLE, this token is then passed into the Standalone Credits API.
- The status of the withdrawal will initially be in the PENDING state and will move to COMPLETED after the standalone credit is processed to the consumer's bank account, at each step a webhook will be triggered to you.

Once a payment has been made through the Giropay service, the customer is only able to make a withdrawal to the bank through which the payment was made. Multiple banks can be used, and the withdrawal will be processed to the bank whose paymentId is given in the request.
The standalone credits should be initiated after an hour of payment initiation.

APIs to use

Create Payment Handle Process Standalone Credit

Giropay Refunds

To process a refund transaction using Giropay:

After the payment is done, the status changes to COMPLETED in the response of payments information, the refund can be initiated using the payment ID.
Create a refund request with the Refunds API.
- POST: /paymenthub/v1/settlements/{settlementsid}/refunds
The request takes an amount, which is equal to what was in the payments, or could be a partial refund with an amount lower than what was in the payments.
Multiple partial refunds can be initiated until the total sum of the amount is lesser than the initial payment amount.
The response contains the details of the payment completed and a unique identifier that could be used to refer to each individual refund.
The status of the refund will be in the SCHEDULED state and moves to PROCESSED after the refund is processed to the customer's bank account, at each step a webhook will be triggered to you.

You can only start a refund transaction if the transaction has been settled/paid.
Refunds should be initiated after an hour of initiating payments.

APIs to use

Create Refund Get Refund

Code Examples

Payment handle - request

{

    "merchantRefNum": "33de25e0-4d58-48ad-a73b-6837d89ea8ea",

    "transactionType": "PAYMENT",

    "accountId": "1021515400",

    "giropay": {       

       "consumerId": "joe.sweet@paysafe.com",

        "countryCode": "DE",

        "websiteId":"10007062"

     },

    "paymentType": "GIROPAY",

    "amount": 1000,

    "currencyCode": "EUR",

    "customerIp": "172.0.0.1",

    "billingDetails": {

        "nickName": "Home",

        "street": "100 Queen",

        "street2": "Unit 201",

        "city": "Toronto",

        "zip": "M5H 2N2",

        "country": "CA"

    },

  

    "returnLinks": [

        {

            "rel": "on_completed",

            "href": "https://usgaminggamblig.com/payment/return/success",

            "method": "GET"

        },

        {

            "rel": "on_failed",

            "href": "https://usgaminggamblig.com/payment/return/failed",

            "method": "GET"

        },

        {

            "rel": "on_cancelled",

            "href": "https://usgaminggamblig.com/payment/return/cancelled",

            "method": "GET"

        },

        {

            "rel": "default",

            "href": "https://usgaminggamblig.com/payment/",

            "method": "GET"

        }

    ]

}

Payment handle - response

{

    "id": "35fb2104-a73f-42bb-8142-80626867d632",

    "paymentType": "GIROPAY",

    "paymentHandleToken": "PHbzGKOoqngDfGT9",

    "merchantRefNum": "33de25e0-4d58-48ad-a73b-6837d89ea8ea",

    "currencyCode": "GBP",

    "txnTime": "2023-02-21T10:48:25Z",

    "billingDetails": {

        "street": "100 Queen",

        "street2": "Unit 201",

        "city": "Toronto",

        "zip": "M5H 2N2",

        "country": "CA"

    },

    "customerIp": "172.0.0.1",

    "status": "INITIATED",

    "links": [

        {

            "rel": "redirect_payment",

            "href": "https://api.qa.paysafe.com/alternatepayments/v1/redirect?accountId=1021515400&paymentHandleId=35fb2104-a73f-42bb-8142-80626867d632&token=eyJhbGciOiJIUzI1NiJ9.eyJhY2QiOiIxMDIxNTE1NDAwIiwicHlkIjoiMzVmYjIxMDQtYTczZi00MmJiLTgxNDItODA2MjY4NjdkNjMyIiwiZXhwIjoxNjc2OTc4MzA1fQ.NHZZL42cFPKFYGwQDpFVwQFfoslXt3j3AOa9lZVjd8Y"

        }

    ],

    "liveMode": false,

    "simulator": "EXTERNAL",

    "usage": "SINGLE_USE",

    "action": "REDIRECT",

    "executionMode": "SYNCHRONOUS",

    "amount": 1000,

    "timeToLiveSeconds": 899,

    "gatewayResponse": {

        "processor": "SKRILL_QCO",

        "sid": "307dad008ba314ed6e97ef20072e1124"

    },

    "returnLinks": [

        {

            "rel": "default",

            "href": "https://usgaminggamblig.com/payment/"

        },

        {

            "rel": "on_failed",

            "href": "https://usgaminggamblig.com/payment/return/failed"

        },

        {

            "rel": "on_completed",

            "href": "https://usgaminggamblig.com/payment/return/success"

        },

        {

            "rel": "on_cancelled",

            "href": "https://usgaminggamblig.com/payment/return/cancelled"

        }

    ],

    "transactionType": "PAYMENT",

    "gatewayReconciliationId": "497a3c95-0f85-4a67-8a9e-414bc24f896b",

    "updatedTime": "2023-02-21T10:48:25Z",

    "statusTime": "2023-02-21T10:48:25Z"

    },

    "giropay": {     

        "consumerId": "joe.sweet@paysafe.com",

        "countryCode": "DE",

        "websiteId":"10007062"

     }

}

Payment request

{

    "merchantRefNum": "5b6e9a70-7116-4810-a010-ed0829a6e24e",

    "amount": 100,

    "currencyCode": "EUR",

    "dupCheck": true,

    "settleWithAuth": true,

    "paymentHandleToken": "PHbzGKOoqngDfGT9",

    "customerIp": "172.0.0.1",

    "description": "Magazine subscription"

}

Payment response

{

    "id": "54049a1f-0759-4b8a-89a0-463363851346",

    "paymentType": "GIROPAY",

    "paymentHandleToken": "PHbzGKOoqngDfGT9",

    "merchantRefNum": "5b6e9a70-7116-4810-a010-ed0829a6e24e",

    "currencyCode": "EUR",

    "settleWithAuth": true,

    "dupCheck": true,

    "txnTime": "2023-02-21T14:12:21Z",

    "billingDetails": {

        "street1": "100 Queen",

        "street2": "Unit 201",

        "city": "Toronto",

        "zip": "M5H 2N2",

        "country": "CA"

    },

    "customerIp": "172.0.0.1",

    "status": "COMPLETED",

    "gatewayReconciliationId": "7374d7ca-c39d-41f5-beb0-f1292c159dc6",

    "amount": 100,

    "availableToRefund": 100,

    "consumerIp": "172.0.0.1",

    "liveMode": false,

    "simulator": "EXTERNAL",

    "updatedTime": "2023-02-21T14:13:08Z",

    "statusTime": "2023-02-21T14:13:08Z",

    "gatewayResponse": {

        "transaction_id": "7374d7ca-c39d-41f5-beb0-f1292c159dc6",

        "amount": "1.00",

        "mb_transaction_id": "320025076",

        "pay_from_email": "elvisstoyanov.psc.payer@sun-mish.com",

        "pay_to_email": "skrill.safetypay+2@paysafe.com",

        "currency": "EUR",

        "merchant_id": "322783146",

        "id": "320025076",

        "processor": "SKRILL_QCO",

        "status": "2",

        "sid": "5322becf0e0b7cd5bee11b2ecf00d9de"

    },

    "availableToSettle": 0

    },

    "giropay": {       

        "consumerId": "joe.sweet@paysafe.com",

        "countryCode": "DE",

        "digitalShopId":"10007062",

 

  },

    "settlements": {

        "amount": 100,

        "txnTime": "2023-02-21T14:12:21.000+0000",

        "availableToRefund": 100,

        "merchantRefNum": "5b6e9a70-7116-4810-a010-ed0829a6e24e",

        "id": "54049a1f-0759-4b8a-89a0-463363851346",

        "status": "COMPLETED"

    }

}

Payment handle - request (Withdrawal/SCT)

{

    "merchantRefNum": "1679649771",

    "transactionType": "STANDALONE_CREDIT",

    "paymentType": "GIROPAY",

    "amount": 419,

    "currencyCode": "EUR",

  

     "giropay": {

        "consumerId": "johncena@gmail.com",

        "paymentId": "18966217-2b3c-48fb-82ad-1e764fe0a008",

        "emailMessage": "emailMessage",

        "emailSubject": "emailSubject"

    }

     

}

Payment handle - response (Withdrawal/SCT)

{

"id": "81af54ea-cca1-4bdc-96b4-f3ef83504cf1",

"merchantRefNum": "1679649741",

"paymentHandleToken": "PHrOaPz39eMImyMe",

"status": "PAYABLE",

"paymentType": "GIROPAY",

"liveMode": false,

"simulator": "INTERNAL",

"usage": "SINGLE_USE",

"action": "NONE",

"executionMode": "SYNCHRONOUS",

"amount": 419,

"currencyCode": "EUR",

"timeToLiveSeconds": 899,

"gatewayResponse": {

"processor": "SKRILL_QCO"

},

"transactionType": "STANDALONE_CREDIT",

"gatewayReconciliationId": "4ac51e23-37e4-4cc5-b5dc-cc23a560594a",

"txnTime": "2023-03-24T09:22:21Z",

"updatedTime": "2023-03-24T09:22:21Z",

"statusTime": "2023-03-24T09:22:21Z",

"links": [

{

"rel": "self",

"href": "http://mtl-dev-app-10.dev.oneplatform.io:8011/alternatepayments/v1/accounts/1679649556/paymenthandles/81af54ea-cca1-4bdc-96b4-f3ef83504cf1"

}

],

"giropay": {

"consumerId": "johncena@gmail.com",

"emailSubject": "emailSubject",

"emailMessage": "emailMessage",

"paymentId": "18966217-2b3c-48fb-82ad-1e764fe0a008"

}

}

Standalone credit - request

{

    "amount": 419,

    "merchantRefNum": "1679650557",

    "paymentHandleToken": "PHrOaPz39eMImyMe"

}

Standalone credit - response

{

"id": "7b44f5f7-3d59-4c83-8ca0-dd6501f87abf",

"gatewayReconciliationId": "AEAAAAFMRE",

"merchantRefNum": "1679650449",

"dupCheck": true,

"amount": 419,

"currencyCode": "EUR",

"paymentType": "GIROPAY",

"paymentHandleToken": "PHrOaPz39eMImyMe",

"liveMode": false,

"simulator": "INTERNAL",

"txnTime": "2023-03-24T09:34:09Z",

"updatedTime": "2023-03-24T09:34:11Z",

"statusTime": "2023-03-24T09:34:11Z",

"status": "PENDING",

"gatewayResponse": {

"status_msg": "scheduled",

"id": "506402464",

"processor": "SKRILL_QCO",

"sid": "2ed348c5ff674c54b7a3f62a7c6f5653",

"status": "1"

},

"links": [

{

"rel": "self",

"href": "http://mtl-dev-app-10.dev.oneplatform.io:8011/alternatepayments/v1/accounts/1679649556/standalonecredits/7b44f5f7-3d59-4c83-8ca0-dd6501f87abf"

}

],

"giropay": {

"consumerId": "johncena@gmail.com",

"emailSubject": "emailSubject",

"emailMessage": "emailMessage",

"paymentId": "18966217-2b3c-48fb-82ad-1e764fe0a008"

}

}

Create refund - request

{

    "amount": 110,

    "merchantRefNum": "1679651216",

    "paymentType": "GIROPAY",

    "currencyCode": "EUR"

}

Create refund - response

{

    "id": "aa6657d4-cf48-4bb8-8cec-82851ff3657e",

    "gatewayReconciliationId": "-1326298067",

    "merchantRefNum": "1679651045",

    "amount": 110,

    "currencyCode": "EUR",

    "paymentType": "GIROPAY",

    "txnTime": "2023-03-24T09:44:05Z",

    "updatedTime": "2023-03-24T09:44:06Z",

    "statusTime": "2023-03-24T09:44:06Z",

    "liveMode": false,

    "simulator": "INTERNAL",

    "status": "COMPLETED",

    "gatewayResponse": {

        "id": "-1326298067",

        "status": "2",

        "merchant_id": "982842053",

        "processor": "SKRILL_QCO"

    },

    "links": [

        {

            "rel": "self",

            "href": "http://mtl-dev-app-10.dev.oneplatform.io:8011/alternatepayments/v1/accounts/1679649556/refunds/aa6657d4-cf48-4bb8-8cec-82851ff3657e"

        },

        {

            "rel": "payment",

            "href": "http://mtl-dev-app-10.dev.oneplatform.io:8011/alternatepayments/v1/accounts/1679649556/payments/18966217-2b3c-48fb-82ad-1e764fe0a008"

        }

    ]

}

Webhooks

Payment Handle

PAYMENT_HANDLE_PAYABLE – This webhook notifies that the payment handle token is created for the required purpose, and it can be executed when the preliminary requirements are completed, the next API call with the payment handle can be done.
PAYMENT_HANDLE_PROCESSING – This webhook is triggered when the customer is successfully redirected to the payment platform page and operation has started for the payment by the customer.
PAYMENT_HANDLE_COMPLETED - This webhook is triggered when the process of the payment handle token is completed after triggering the next API.
PAYMENT_HANDLE_EXPIRED - This webhook is triggered when the next step is not initiated after the payment handle is created within the given time frame, the duration can be seen in the response to /paymenthub/v1/paymenthandles API under the tag timeToLiveSeconds.
PAYMENT_HANDLE_FAILED - This webhook is triggered when the customer is successfully redirected to the payment platform page, but some technical error occurred and final communication couldn't reach to Paysafe.

Payments

PAYMENT_PENDING -The payment is pending because the transaction hasn't been completed from the bank account to Skrill wallet to you.
PAYMENT_COMPLETED/SETTLEMENT_COMPLETED - The payment was completed successfully.
PAYMENT_FAILED - This webhook is triggered when the payment fails during the process.

Standalone Credits/Withdrawal

SA_CREDIT_FAILED – This webhook is triggered in case the transaction was initially completed and later failed due to some settlement error.
SA_CREDIT_CANCELLED - This webhook is triggered when the transaction was canceled after it was completed.
SA_CREDIT_ERRORED - This webhook is used when there is a technical error during the initiation of a transaction.
SA_CREDIT_PENDING - This webhook is triggered when the withdrawal has been initiated but due to various bank delay reasons or time zone issues the actual money transfer has not happened.

Refunds

REFUND_FAILED - This webhook is triggered when the refund is initiated but failed due to a functional error.

Example – refund amount is more than the Payment amount.
REFUND_COMPLETED - This webhook is triggered when the refund has been successfully transferred from your account to the customer's chosen bank account.
REFUND_PENDING - This webhook is triggered when refund has been initiated but due to various bank delay reasons or time zone issues the actual money transfer has not happened.

Simulation Cases

Simulator Settings: In the request headers, pass INTERNAL value for the simulator field.

Standalone Credit Simulations

Standalone Credit Amount	Initial Status	Next Status Transition	Status Transition Delay (in seconds)
24.19	PENDING	COMPLETED	5
24.29	PENDING	FAILED	10
25.19	PENDING	COMPLETED	10
25.29	PENDING	FAILED	15
26.19	ERROR	ERROR	0

Any standalone credit transaction other than the amounts mentioned will remain in PENDING status.

Refund simulations

Refund Amount	Initial Status	Next Status Transition	Status Transition Delay (in seconds)
24.21	PENDING	COMPLETED	5
24.31	PENDING	FAILED	10
26.31	FAILED	FAILED	0

If the refund amount exceeds the original payment amount, the refund will be in FAILED status.
Any refund transaction other than the amounts mentioned will remain in COMPLETED status.

Error Codes and Transaction Status

Status Mapping

Skrill PSP Status	Status Description	Paysafe Status Code	Paysafe Status Reason
-2	failed	FAILED	An external Gateway error occurred.
2	processed	COMPLETED
0	pending	PENDING
1	pending	PENDING

Initiate Payment Error Codes

Skrill PSP Return code	Message Code	Paysafe ERROR Message	Paysafe ERROR Details	Paysafe status	Comments
-2	failed	External Gateway Error	An external Gateway error occurred.	FAILED	Failed (-2) is typically sent when the customer tries to pay, but Skrill's provider declines the transaction. It can also be sent if the transaction is declined by Skrill’s internal fraud engine.

Initiate SCT Error Codes

Skrill PSP Return code	Message Code	Paysafe ERROR Message	Paysafe ERROR Details	Paysafe status	Comments
-2	failed	External Gateway Error	An external Gateway error occurred.	FAILED	Failed (-2) can occur in case of below scenarios. Standalone credit amount exceeds account balance. The referenced transaction was not processed. Other generic errors and technical errors.

Skrill PSP Return code

Message Code

Paysafe ERROR Message

Paysafe ERROR Details

Paysafe status

Comments

-2

failed

External Gateway Error

An external Gateway error occurred.

FAILED

Failed (-2) can occur in case of below scenarios.

Standalone credit amount exceeds account balance.
The referenced transaction was not processed.
Other generic errors and technical errors.

Initiate Refund Error Codes

Skrill PSP Return code	Message Code	Paysafe ERROR Message	Paysafe ERROR Details	Paysafe status	Comments
-2	failed	External Gateway Error	An external Gateway error occurred.	FAILED	Failed (-2) can occur in case of below scenarios. Refund amount exceeds account balance. Transaction has already been exceeded. Other generic errors.

Skrill PSP Return code

Message Code

Paysafe ERROR Message

Paysafe ERROR Details

Paysafe status

Comments

-2

failed

External Gateway Error

An external Gateway error occurred.

FAILED

Failed (-2) can occur in case of below scenarios.

Refund amount exceeds account balance.
Transaction has already been exceeded.
Other generic errors.

For more details on errors, see Payments API.

Was this page helpful?

On this Page

Features
Setup Requirements
Transaction types
Typical Scenarios
Giropay Payment
Auto-Settlement and Auto-Refund
Giropay Withdrawal/Standalone Credits
Giropay Refunds
Code Examples
Webhooks
Simulation Cases
Error Codes and Transaction Status

Search Overlay

Giropay

Was this page helpful?

Thank you for your response!