What does payment capture do?

Capturing a payment is the act of settling funds after the payment is authorized.

A capture payment call is a request to a payment processor to actually charge the customer’s account and transfer the funds to the merchant's account. This typically occurs after an authorization payment call has been made, ensuring that the funds will be available when the capture payment request is made.

The capture payment call is an essential part of the payment process, as it ensures that the merchant receives the funds that they are owed for the goods or services that they have provided.

How to capture a payment

Primer enables you to fully or partially capture an authorized payment across all your processors in a unified way.

In order to capture a payment, its status must be AUTHORIZED. If the capture is successful, the payment status will be automatically updated to:

• SETTLED if the processor captured the payment immediately
• SETTLING if the processor needs more time to capture the payment i.e. asynchronous capture. See the section below for more.
• PARTIALLY_SETTLED if only a part of the authorized amount was captured - see the section below for more.

All capture calls are sent to the processor used in the authorization request.

To check the status of the payment, you can use:

• the Payments timeline in the Primer Dashboard
• payment webhooks to receive status updates
• the GET payment API call

Capture a payment with Primer in two ways:

Capture a payment via Workflows

Use Workflows to set up business logic on when and how to capture a payment - without writing a single line of code.

In your payment workflow, once you have an "Authorize payment" Action set up from the Primer Payments app, simply add your "Capture payment" Action.

You can configure any additional business flows in between your "Authorize payment" and "Capture payment" Actions, creating powerful payment flows that suit your needs.

For example, you may want to send an email to the customer immediately after a successful authorization before capturing the payment - this becomes very easy with Primer.

Learn more here about the Payments app and the "Capture payment" Action.

Capture a payment via Payments API

Capture a payment using the Payments API - see the API reference for the details.

12345

curl --request POST \     --url https://api.sandbox.primer.io/payments/<YOUR_PAYMENT_ID>/capture \     --header 'X-API-KEY: <YOUR_API_KEY>' \     --header 'X-API-VERSION: 2.2' \     --header 'X-Idempotency-Key: <YOUR_IDEMPOTENCY_KEY>'

Include the Primer payment ID in the request, which you will have received as part of the payment creation and authorization.

The payload sent in the capture request is completely optional and can be used to partially capture the payment. See the section below to learn more about partial captures.

There are several use cases where you may want to capture via API versus Workflows, including scenarios where the full amount isn’t known at the time of authorization.

An example is micromobility services where the final amount is based on the duration of the ride post-authorization. As a result, it may be easier to trigger capturing the payment based on internal information rather than via a workflow.

Handle asynchronous capture

Capture can be asynchronous i.e. once the capture call is sent to the processor, it can take some time for the payment to become SETTLED.

As a result, it’s recommended you use payment webhooks to receive updates on when the payment becomes SETTLED and not rely on the response to the capture call, which will only tell you that the capture request was successful, not necessarily that the payment is SETTLED.

When you attempt to capture a payment with such a processor, the payment status is first set to SETTLING. The processor then automatically notifies Primer once the capture is completed, which sets the payment status to SETTLED and the payment status webhook event to be sent to you.

Read more here on how to handle webhooks.

Partial Capture

You can choose to capture an amount less than the full authorization amount. There are several use cases where this is valuable, including:

• the final amount isn't known at authorization and ends up being less than the authorized amount.
• the order is made of multiple physical products that should be shipped separately - do multiple partial captures, one per product shipped.

You can partially capture a payment via both Workflows and the Payments API. There are two inputs you can provide which are needed to partial capture:

• amount - the amount you want to capture. If no amount is specified, it defaults to the full amount.
• final - if True (it is by default), no subsequent captures are allowed, but if False, subsequent capture calls are supported.

So, for a partial capture, simply set:

• the amount input to less than the authorization amount

If you want to make multiple partial captures, set:

• final to False

For subsequent capture requests, the default amount is then calculated by <amount authorized> - <amount already captured>.