IPaymentProvider

Methods

initiatePayment

This methods sends a request to the third-party provider to initialize the payment. It's called when the payment session is created.

For example, in the Stripe provider, this method is used to create a Payment Intent for the customer.

Parameters

dataCreatePaymentProviderSessionRequired

The data necessary to initiate the payment.

Returns

PromisePromise<PaymentProviderSessionResponse | PaymentProviderError>Required

Either the payment's data, which is stored in the data field of the payment session, or an error object.

updatePayment

This method is used to update a payment associated with a session in the third-party provider.

Parameters

contextUpdatePaymentProviderSessionRequired

The data related to the update.

Returns

PromisePromise<PaymentProviderSessionResponse | PaymentProviderError>Required

Either the payment's data or an error object.

deletePayment

This method is called before a payment session is deleted. It's used to perform any actions necessary before the deletion.

Parameters

paymentSessionDataRecord<string, unknown>Required

The data field of the Payment Session.

Returns

PromisePromise<Record<string, unknown> | PaymentProviderError>Required

Either an error object or an empty object.

authorizePayment

This method is called when a payment session should be authorized. You can interact with a third-party provider and perform the necessary actions to authorize the payment.

Refer to this guide to learn more about how this fits into the payment flow and how to handle required actions.

Parameters

paymentSessionDataRecord<string, unknown>Required

The data field of the payment session.

contextRecord<string, unknown>Required

The context of the authorization.

Returns

PromisePromise<PaymentProviderAuthorizeResponse | PaymentProviderError>Required

The authorization details or an error object. If the authorization details are returned, the data and status field are set in the associated payment session.

capturePayment

This method is called when a payment should be captured. The payment is captured in one of the following scenarios:

• The payment provider supports automatically capturing the payment after authorization.
• The merchant requests to capture the payment after its associated payment session was authorized.
• A webhook event occurred that instructs the payment provider to capture the payment session. Learn more about handing webhook events in this guide

In this method, you can interact with the third-party provider and perform any actions necessary to capture the payment.

Parameters

paymentSessionDataRecord<string, unknown>Required

The data field of the payment.

Returns

PromisePromise<Record<string, unknown> | PaymentProviderError>Required

Either an error object or a value that's stored in the data field of the payment.

refundPayment

This method is called when a payment should be refunded. This is typically triggered manually by the merchant.

In this method, you can interact with the third-party provider and perform any actions necessary to refund the payment.

Parameters

paymentSessionDataRecord<string, unknown>Required

The data field of a Payment.

refundAmountBigNumberInputRequired

The amount to refund.

Returns

PromisePromise<Record<string, unknown> | PaymentProviderError>Required

Either an error object or an object that's stored in the data field of the payment.

retrievePayment

This method is used to provide a uniform way of retrieving the payment information from the third-party provider.

For example, in Stripe’s payment provider this method is used to retrieve the payment intent details from Stripe.

Parameters

paymentSessionDataRecord<string, unknown>Required

The data field of a payment session. Make sure to store in the data field any necessary data that would allow you to retrieve the payment data from the third-party provider.

Returns

PromisePromise<Record<string, unknown> | PaymentProviderError>Required

Either an error object or the payment's data retrieved from a third-party provider.

cancelPayment

This method is called when a payment is canceled.

In this method, you can interact with the third-party provider and perform any actions necessary to cancel the payment.

Parameters

paymentSessionDataRecord<string, unknown>Required

The data field of the payment.

Returns

PromisePromise<Record<string, unknown> | PaymentProviderError>Required

Either an error object or a value that's stored in the data field of the payment.

getPaymentStatus

This method is used to get the status of a payment or a payment session.

Parameters

paymentSessionDataRecord<string, unknown>Required

The data field of a payment as a parameter. You can use this data to interact with the third-party provider to check the status of the payment if necessary.

Returns

PromisePromise<PaymentSessionStatus>Required

The status of the payment or payment session.

getWebhookActionAndData

The method is called when a webhook event is received for this provider.

The method is responsible for normalizing the received event and inform the Payment Module of actions to perform, such as authorize or capture payment.

Learn more about handling webhook events in this guide

Parameters

dataobjectRequired

The webhook event's details.

data.dataRecord<string, unknown>Required

The parsed webhook body.

data.rawDatastring | BufferRequired

The raw webhook request body.

data.headersRecord<string, unknown>Required

The headers of the webhook request.

Returns

PromisePromise<WebhookActionResult>Required

The method is called when a webhook event is received for this provider. The method is responsible for normalizing the received event and inform the Payment Module of actions to perform, such as authorize or capture payment. Learn more about handling webhook events in this guide