Wooshpay Direct API

Ensure PCI compliance for card as payment method.

Anyone involved with the processing, transmission, or storage of card data must comply with the Payment Card Industry Data Security Standards (PCI DSS). PCI compliance is a shared responsibility and applies to both WooshPay and your business. When accepting payments, you must do so in a PCI compliant manner. The simplest way for you to be PCI compliant is to never see (or have access to) card data at all.

Use the Payment Intents API to build an integration that can handle complex payment flows. It tracks a payment from creation through checkout, and triggers additional authentication steps when required.

Some of the advantages of using the Payment Intents API include:

Automatic authentication handling

No double charges

No idempotency key issues

Support for Strong Customer Authentication (SCA) and similar regulatory changes

A complete set of APIs

Use the Payment Intents API together with the Setup Intents and Payment Methods APIs. These APIs help you handle dynamic payments (for example, additional authentication like 3D Secure) and prepare you for expansion to other countries while allowing you to support new regulations and regional payment methods.

Building an integration with the Payment Intents API involves two actions: creating and confirming a PaymentIntent. In the following paragraph, we will Introduction the payment intent API by payment flow:

Non-3DS payment flow

3DS payment flow

1. Non-3DS payment flow

The non-3ds payment flow provides a clear scope of what's WooshPay role is regarding the whole payment process from the customer initiating the payment till finalized it. WooshPay uses a PaymentIntent object to represent your intent to collect payment from a customer, tracking charge attempts and payment state changes throughout the process.

https://kroki.io/plantuml/svg/eNp9UrtuwzAM3P0V_AH_gIcgRYaiW9AOnVmZjgnoYYi0jfbrS9VJYRlFNUig7njkUTqLYtY5-Gaykx1PGBUus2gKlAEFHNSQZ7KjAFwBb5SXLUOq-_eUZJzw8wfRxpZrT447eE6gCQwJRXDCGxnE7Uk6odhDyr3JcRxSDqicYoNOeUElKyBG0w4umUp83TReotq-o2kj2hZBeCWdc4RI64Hc055ehbtWrzkt3BN8sPccb9CTInsBtD4Hjuj5ix5O7h5sHgY-3N0T_rKQ4sA5_O-hMJ9UKUz6W-borRKAlXW0ZNRZDh5ls1S1l0lmv6tqT1tcOKONaT3SqiHtAsuydTZh-0_fIgXUXA==

The payment methods shown to customers during the checkout process are also included on the PaymentIntent. You can include all the payment method that you want from listing them using payment_method_data parameter.

The PaymentIntent contains a client secret, a key that’s unique to the individual PaymentIntent. To use the client secret, you must obtain it from the PaymentIntent on your server and pass it to the client side. You can use different approaches to get the client secret to the client side.

Request Create a PaymentIntent

{
    "amount":1,
    "currency":"USD",
    "confirm":true,
    "payment_method_options":{
        "card":{
            "request_three_d_secure":"auto"
        }
    },
    "payment_method_data":{
        "type":"card",
        "card":{
            "cvc":"123",
            "number":"4111111111111111",
            "exp_month":"03",
            "exp_year":"2027"
        }
    },
    "merchant_order_id":"id1111",
    "return_url":"https://wooshpay.com"
}

Response

{
    "id":"pi_1583366366029676544",
    "object":"payment_intent",
    "created":1666338934000,
    "currency":"USD",
    "amount":1,
    "status":"succeeded",
    "description":null,
    "metadata":null,
    "livemode":false,
    "merchant_order_id":"id1111",
    "client_secret":"pi_1583366366029676544_secret_WKtUP8YmKmUKxcQPV0Zrmxym",
    "last_payment_error":null,
    "next_action":"",
    "payment_method_types":"[\"card\",\"alipay\",\"wechat_pay\",\"alipayplus\",\"klarna\",\"ideal\",\"giropay\",\"sofort\",\"eps\",\"trustly\",\"bancontact\",\"p24\",\"sepa\"]",
    "receipt_email":null,
    "statement_descriptor":null,
    "statement_descriptor_suffix":null,
    "cancel_at":"",
    "cancellation_reason":null,
    "confirmation_method":"automatic",
    "payment_method_options":"{\"card\":{\"request_three_d_secure\":\"auto\",\"capture_method\":\"automatic\"}}",
    "3ds_status":null,
    "amount_capturable":null
}

2. 3DS payment flow

Although Europe is phasing it in unevenly, you should prepare your payment flows to be ready for SCA as soon as possible if SCA regulations impact you. The Strong Customer Authentication regulation in Europe requires the use of 3DS for card payments. 3DS is optional in other regions but you can still use it as a tool to reduce fraud.

For 3DS, typically, you direct the customer to an authentication page on their bank’s website, and they enter a password associated with the card or a code sent to their phone.

Request Create a PaymentIntent

{
    "amount":1,
    "currency":"USD",
    "confirm":true,
    "payment_method_options":{
        "card":{
            "request_three_d_secure":"any",
            "capture_method":"automatic"
        }
    },
    "payment_method_data":{
        "type":"card",
        "card":{
            "cvc":"123",
            "number":"4111111111111111",
            "exp_month":"03",
            "exp_year":"2027"
        }
    },
    "merchant_order_id":"id1111",
    "return_url":"https://wooshpay.com"
}

Response

{
    "id":"pi_1583367070215569408",
    "object":"payment_intent",
    "created":1666339102000,
    "currency":"USD",
    "amount":1,
    "status":"requires_action",
    "description":null,
    "metadata":null,
    "livemode":false,
    "merchant_order_id":"id1111",
    "client_secret":"pi_1583367070215569408_secret_gXwuHGXjHgMqVw35oBInuYyC",
    "last_payment_error":null,
    "next_action":"{\"ddc_redirect\":{\"return_url\":\"https://wooshpay.com\",\"url\":\"https://jstest.wooshpay.com/v1/3ds/index.html?c=2&type=ddc&dataId=pi_1583367070215569408&token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwYXlsb2FkIjp7InJlcXVlc3R0eXBlZGVzY3JpcHRpb25zIjpbIlRIUkVFRFFVRVJZIl0sImV4cGlyeWRhdGUiOiIwMy8yMDI3IiwiY3VycmVuY3lpc28zYSI6IlVTRCIsInNpdGVyZWZlcmVuY2UiOiJ0ZXN0X3N3b29zaHRyYW5zZmVybHRkOTczMjkiLCJiYXNlYW1vdW50IjoiMSIsInBhbiI6IjQxMTExMTExMTExMTExMTEiLCJzZWN1cml0eWNvZGUiOiIxMjMiLCJhY2NvdW50dHlwZWRlc2NyaXB0aW9uIjoiRUNPTSIsIm9yZGVycmVmZXJlbmNlIjoicGlfMTU4MzM2NzA3MDIxNTU2OTQwOCJ9LCJpc3MiOiJqd3RAc3dvb3NodHJhbnNmZXIuY29tIiwiaWF0IjoxNjY2MzM5MTAyfQ.L7CEYYRo95SesCt6WIsXr51MgHZKjkIDfmkooFTaUuo\"},\"type\":\"ddc_redirect\"}",
    "payment_method_types":"[\"card\",\"alipay\",\"wechat_pay\",\"alipayplus\",\"klarna\",\"ideal\",\"giropay\",\"sofort\",\"eps\",\"trustly\",\"bancontact\",\"p24\",\"sepa\"]",
    "receipt_email":null,
    "statement_descriptor":null,
    "statement_descriptor_suffix":null,
    "cancel_at":"",
    "cancellation_reason":null,
    "confirmation_method":"automatic",
    "payment_method_options":"{\"card\":{\"request_three_d_secure\":\"any\",\"capture_method\":\"automatic\"}}",
    "3ds_status":null,
    "amount_capturable":null
}

Controlling when to present the 3D Secure flow

WooshPay triggers 3DS automatically if required by a regulatory mandate such as Strong Customer Authentication. When you run 3D Secure, WooshPay requires your customer to perform authentication to complete the payment if 3DS authentication is available for a card.

If a card doesn’t support 3DS or an error occurs during the authentication process, the payment proceeds normally. When this occurs, liability doesn’t generally shift to the issuer, as a successful 3DS authentication hasn’t taken place.

auto
The default parameter for 3DS is auto, WooshPay's risk control will determine to do 3DS or not. To trigger 3DS manually, set payment_method_options[card][request_three_d_secure] to any when creating or confirming a PaymentIntent or SetupIntent.

any
When you set request_three_d_secure to any, WooshPay requires your customer to perform authentication to complete the payment successfully if 3DS authentication is available for a card. If it’s not available for the given card, the payment proceeds normally.

A complete set of APIs#

1. Non-3DS payment flow#

2. 3DS payment flow#

Controlling when to present the 3D Secure flow#

A complete set of APIs

1. Non-3DS payment flow

2. 3DS payment flow

Controlling when to present the 3D Secure flow