> ## Documentation Index
> Fetch the complete documentation index at: https://primer.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Approve a payment attempt
>
Approve a payment attempt that is awaiting merchant approval, and trigger payment authorization on Primer's side.
This endpoint is the merchant entry-point of the **Backend-Driven CIT (MANUAL approval)** flow: after the SDK tokenises a payment method and the merchant backend has decided the payment should proceed (e.g. after a fraud check or inventory validation), the backend calls this endpoint to hand off orchestration to Primer (3DS, retries, webhooks).
The `paymentAttemptId` is the idempotency key: concurrent or retried calls converge on a single downstream payment.
## OpenAPI
````yaml https://api.schemas.primer.io/api-reference/v2.4/openapi.yaml post /payment-attempts/{id}/approve
openapi: 3.0.2
info:
x-logo:
url: https://apidocs.primer.io/docs/assets/images/primer-logo.svg
title: Primer API
version: '2.4'
description: >-
This API enforces a timeout of 90 seconds for all requests. A 504 response
indicates a timeout has occurred.
servers:
- url: https://api.sandbox.primer.io
- url: https://api.primer.io
security:
- ApiKeyAuth: []
tags:
- name: Client Session API
- name: Payments API
- name: Payment Methods API
- name: Payment Attempts API
paths:
/payment-attempts/{id}/approve:
post:
tags:
- Payment Attempts API
summary: Approve a payment attempt
description: >
Approve a payment attempt that is awaiting merchant approval, and
trigger payment authorization on Primer's side.
This endpoint is the merchant entry-point of the **Backend-Driven CIT
(MANUAL approval)** flow: after the SDK tokenises a payment method and
the merchant backend has decided the payment should proceed (e.g. after
a fraud check or inventory validation), the backend calls this endpoint
to hand off orchestration to Primer (3DS, retries, webhooks).
The `paymentAttemptId` is the idempotency key: concurrent or retried
calls converge on a single downstream payment.
operationId: approve_payment_attempt_payment_attempts__id__approve_post
parameters:
- required: true
schema:
title: Payment Attempt ID
type: string
format: uuid
name: id
description: ID of the payment attempt to approve.
in: path
- $ref: '#/components/parameters/ApiVersionHeader'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ApprovePaymentAttemptResponse'
example:
paymentAttemptId: 6c5d3a30-3c2e-4f55-9d8e-5b3d5e3a5c7f
merchantPaymentId: IHQlakKC
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/400ErrorResponse'
example:
error:
errorId: BadRequest
description: The request body could not be parsed.
diagnosticsId: '1234567898'
'404':
description: >-
Payment attempt not found, or its client session belongs to another
tenant
content:
application/json:
schema:
$ref: '#/components/schemas/404ErrorResponse'
example:
error:
errorId: PaymentAttemptNotFound
description: The payment attempt could not be found.
diagnosticsId: '1234567898'
'409':
description: Payment attempt cannot be approved in its current state
content:
application/json:
schema:
$ref: '#/components/schemas/409ErrorResponse'
examples:
ClientSessionNotManual:
value:
error:
errorId: ClientSessionNotManual
description: >-
The client session must be in MANUAL approval mode to
approve a payment attempt.
diagnosticsId: '1234567898'
InvalidPaymentAttemptTransition:
value:
error:
errorId: InvalidPaymentAttemptTransition
description: >-
The payment attempt is not the current attempt for its
session, or it is already in a terminal state.
diagnosticsId: '1234567898'
IdempotencyKeyAlreadyExists:
value:
error:
errorId: IdempotencyKeyAlreadyExists
description: >-
A concurrent or duplicate approve has already created a
payment for this payment attempt.
diagnosticsId: '1234567898'
'410':
description: Payment attempt has expired
content:
application/json:
schema:
$ref: '#/components/schemas/410ErrorResponse'
example:
error:
errorId: PaymentAttemptExpired
description: >-
The payment attempt has expired and can no longer be
approved.
diagnosticsId: '1234567898'
'422':
description: Request failed validation
content:
application/json:
schema:
$ref: '#/components/schemas/422ErrorResponse'
example:
error:
errorId: RequestValidationError
description: >-
We were unable to validate your request, please check your
payload against /docs/api.
diagnosticsId: '1234567898'
components:
parameters:
ApiVersionHeader:
required: true
schema:
title: X-API-VERSION
type: string
example: '2.4'
name: X-API-VERSION
description: Specifies the version of the API to use. This must be set to `2.4`.
in: header
schemas:
ApprovePaymentAttemptResponse:
title: ApprovePaymentAttemptResponse
type: object
required:
- paymentAttemptId
- merchantPaymentId
properties:
paymentAttemptId:
title: Payment Attempt ID
type: string
format: uuid
description: ID of the approved payment attempt.
merchantPaymentId:
title: Merchant Payment ID
type: string
description: >-
ID of the payment created on Primer's side as a result of the
approval. Use this to look up the payment via the Payments API.
400ErrorResponse:
title: 400ErrorResponse
type: object
required:
- error
properties:
error:
allOf:
- $ref: '#/components/schemas/ErrorObject'
- type: object
properties:
paymentId:
title: Payment ID
type: string
description: Payment ID of the related pay
paymentStatus:
title: Status
type: string
description: Status of the related payment
404ErrorResponse:
title: 404ErrorResponse
type: object
required:
- error
properties:
error:
$ref: '#/components/schemas/ErrorObject'
409ErrorResponse:
title: 409ErrorResponse
type: object
required:
- error
properties:
error:
allOf:
- $ref: '#/components/schemas/ErrorObject'
- type: object
properties:
paymentId:
title: Payment ID
type: string
description: Payment ID of the related payment
paymentStatus:
title: Status
type: string
description: Status of the related payment
410ErrorResponse:
title: 410ErrorResponse
type: object
required:
- error
properties:
error:
$ref: '#/components/schemas/ErrorObject'
422ErrorResponse:
title: 422ErrorResponse
type: object
required:
- error
properties:
error:
$ref: '#/components/schemas/ErrorObject'
ErrorObject:
title: Error
type: object
description: An object containing information about the error that occurred.
required:
- errorId
- description
properties:
errorId:
title: Error ID
type: string
description: An error ID
description:
title: Error description
type: string
description: A human readable description of the error
recoverySuggestion:
title: Recovery Suggestion
type: string
description: A suggestion on how to recover from the error.
diagnosticsId:
title: Error diagnostics ID
type: string
description: >-
An ID that you can quote when contacting the Primer support team via
our [Support
Portal](https://primerapi.atlassian.net/servicedesk/customer/portal/11).
validationErrors:
title: Validation Errors
type: array
items:
type: object
description: Returned in case of a badly formed request
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: X-API-KEY
````