​
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

Some non-card payment methods will automatically capture the payment after the authorization.
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: Capture a payment with Primer in two ways:

Workflows

Automate sophisticated payment flows to capture your payments.

Payments API

Programmatically capture your payments via API based on your business logic.

​
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.
Example workflow

Example workflow

Asynchronous capture considerations still apply to the “Capture payment” action in Workflows. It’s recommended to use Primer’s payment webhooks to confirm when the payment status is SETTLED.
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.
BASH
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

Not all processors and payment methods support partial capture. Please see the details of the specific processor or payment method to learn more about the capabilities supported.
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>.

​
Refunds Over Partial Captures

Primer also supports refunds over partial captures, giving you more flexibility in managing your payments. This feature is particularly useful for scenarios like marketplaces or logistics-driven workflows. For example, you can capture payments once per seller in a marketplace or once per shipment, ensuring your payment process aligns with your business operations. Each partial capture is uniquely identified by a transactionEventId, allowing you to target specific partial captures for refunds with precision and ease. Limitations to Be Aware Of While these features are designed to enhance your payment workflows, there is one important consideration:
  • Concurrent Partial Captures: Currently Primer API have certain limitations around handling multiple partial captures at the same time, so we highly recommend to make submit them in sequential manner.
If you want to use this feature, please contact us to ensure we can accompany you through the implementation and help address any specific needs or challenges.