# Finalize a pending payment

> Finalize a pending payment being made by a Bolt logged-in shopper. Upon receipt of a finalized payment result, payment success should be communicated to the shopper.

Source: https://help.boltapp.com/api-reference/embeddable-checkout-v3/payments/paymentsaction

`POST /payments/{id}`

## OpenAPI definition

This endpoint as it appears in the OpenAPI document, with every schema it references included.

```json
{
  "openapi": "3.2.0",
  "info": {
    "version": "3.3.22",
    "title": "Bolt API Reference",
    "description": "A comprehensive Bolt API reference for interacting with Accounts, Payments, Orders and more.",
    "termsOfService": "https://www.boltapp.com/end-user-terms",
    "contact": {
      "name": "Bolt",
      "email": "merchantsupport@boltapp.com",
      "url": "https://help.boltapp.com/api-bolt/"
    }
  },
  "servers": [
    {
      "url": "https://{environment}.boltapp.com/v3",
      "variables": {
        "environment": {
          "enum": [
            "api",
            "api-sandbox"
          ],
          "default": "api-sandbox"
        }
      }
    }
  ],
  "paths": {
    "/payments/{id}": {
      "post": {
        "summary": "Finalize a pending payment",
        "operationId": "paymentsAction",
        "x-speakeasy-group": "Payments.LoggedIn",
        "x-speakeasy-name-override": "PerformAction",
        "description": "Finalize a pending payment being made by a Bolt logged-in shopper. Upon receipt of a finalized payment result, payment success should be communicated to the shopper.",
        "tags": [
          "Payments"
        ],
        "security": [
          {
            "oauth": [
              "bolt.account.manage"
            ],
            "api-key": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/x-publishable-key"
          },
          {
            "$ref": "#/components/parameters/x-merchant-client-id"
          },
          {
            "in": "path",
            "name": "id",
            "schema": {
              "type": "string",
              "examples": [
                "iKv7t5bgt1gg"
              ]
            },
            "required": true,
            "description": "The ID of the payment to operate on"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/payment-action-request"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The action was successfully applied to the pending payment",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/payment-response"
                },
                "examples": {
                  "finalized": {
                    "$ref": "#/components/examples/payment-response-finalized"
                  }
                }
              }
            }
          },
          "4XX": {
            "$ref": "#/components/responses/response-4xx"
          },
          "default": {
            "$ref": "#/components/responses/response-default"
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "x-publishable-key": {
        "description": "The publicly shareable identifier used to identify your Bolt merchant division.",
        "in": "header",
        "name": "X-Publishable-Key",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "x-merchant-client-id": {
        "description": "A unique identifier for a shopper's device, generated by Bolt. The value is retrieved with `Bolt.state.merchantClientId` in your frontend context, per-shopper. This header is required for proper attribution of this operation to your analytics reports. Omitting this header may result in incorrect statistics.",
        "in": "header",
        "name": "X-Merchant-Client-Id",
        "required": false,
        "schema": {
          "type": "string"
        }
      }
    },
    "schemas": {
      "payment-action-request": {
        "type": "object",
        "required": [
          ".tag"
        ],
        "properties": {
          ".tag": {
            "type": "string",
            "enum": [
              "finalize",
              "finalize_threeds_payment"
            ],
            "examples": [
              "finalize"
            ]
          },
          "redirect_result": {
            "type": "string",
            "description": "Optional redirect result token required for an APM payment (excluding PayPal).",
            "examples": [
              "eyJ0cmFuc"
            ]
          }
        }
      },
      "payment-response": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/payment-response-finalized"
          },
          {
            "$ref": "#/components/schemas/payment-response-pending"
          },
          {
            "$ref": "#/components/schemas/payment-response-three-ds-required"
          }
        ],
        "discriminator": {
          "propertyName": ".tag",
          "mapping": {
            "finalized": "#/components/schemas/payment-response-finalized",
            "pending": "#/components/schemas/payment-response-pending",
            "three_ds_required": "#/components/schemas/payment-response-three-ds-required"
          }
        }
      },
      "payment-response-finalized": {
        "type": "object",
        "required": [
          ".tag",
          "status",
          "transaction"
        ],
        "properties": {
          ".tag": {
            "type": "string",
            "enum": [
              "finalized"
            ],
            "x-order": 0,
            "examples": [
              "finalized"
            ]
          },
          "id": {
            "type": "string",
            "format": "id",
            "x-order": 1,
            "examples": [
              "iKv7t5bgt1gg"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "success"
            ],
            "examples": [
              "success"
            ]
          },
          "transaction": {
            "$ref": "#/components/schemas/transaction"
          },
          "co_funding_summary": {
            "description": "Co-funding details for this payment, if co-funding was used.",
            "anyOf": [
              {
                "$ref": "#/components/schemas/co-funding-summary"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "transaction": {
        "type": "object",
        "properties": {
          "reference": {
            "type": "string",
            "examples": [
              "OBYG-X1PX-FN55"
            ]
          },
          "authorizations": {
            "description": "Payment authorization events attached to a transaction",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/transaction-authorization"
            }
          }
        }
      },
      "transaction-authorization": {
        "type": "object",
        "properties": {
          "processor_reference": {
            "type": "string",
            "examples": [
              "123456789XYZ"
            ]
          },
          "processor_response": {
            "$ref": "#/components/schemas/processor-response"
          }
        }
      },
      "processor-response": {
        "description": "Raw authorization response from the payment processor",
        "properties": {
          "content_type": {
            "type": "string",
            "examples": [
              "application/json"
            ]
          },
          "api_version": {
            "type": "string",
            "examples": [
              "3.3"
            ]
          },
          "text": {
            "type": "string",
            "examples": [
              "<?xml version=\"1.0\" encoding=\"UTF-8\"?> <transaction> <id>bfraj39q</id> <status>authorized</status> <type>sale</type> <currency-iso-code>USD</currency-iso-code> <amount>57.71</amount> <amount-requested>57.71</amount-requested> <merchant-account-id>GenericMerchant</merchant-account-id> <order-id>ORDER123456</order-id> <created-at type=\"datetime\">2024-11-20T12:36:53Z</created-at> <updated-at type=\"datetime\">2024-11-20T12:36:54Z</updated-at> <customer> <first-name>John</first-name> <last-name>Doe</last-name> <email>example@example.com</email> <phone>1234567890</phone> <international-phone></international-phone> </customer> <billing> <first-name>John</first-name> <last-name>Doe</last-name> <street-address>123 Generic St</street-address> <locality>GenericCity</locality> <region>GenericRegion</region> <postal-code>12345</postal-code> <country-name>GenericCountry</country-name> <country-code-alpha2>GC</country-code-alpha2> <country-code-alpha3>GCR</country-code-alpha3> <country-code-numeric>999</country-code-numeric> <international-phone></international-phone> </billing> <refund-ids type=\"array\"></refund-ids> <partial-settlement-transaction-ids type=\"array\"></partial-settlement-transaction-ids> <shipping> <international-phone></international-phone> </shipping> <custom-fields></custom-fields> <account-funding-transaction type=\"boolean\">false</account-funding-transaction> <avs-postal-code-response-code>M</avs-postal-code-response-code> <avs-street-address-response-code>M</avs-street-address-response-code> <cvv-response-code>I</cvv-response-code> <processor-authorization-code>123456</processor-authorization-code> <processor-response-code>1000</processor-response-code> <processor-response-text>Approved</processor-response-text> <tax-exempt type=\"boolean\">false</tax-exempt> <processed-with-network-token type=\"boolean\">false</processed-with-network-token> <credit-card> <image-url>https://assets.braintreegateway.com/payment_method_logo/unknown.png?environment=production</image-url> <is-network-tokenized type=\"boolean\">false</is-network-tokenized> <prepaid>Unknown</prepaid> <healthcare>Unknown</healthcare> <debit>Unknown</debit> <durbin-regulated>Unknown</durbin-regulated> <commercial>Unknown</commercial> <payroll>Unknown</payroll> <issuing-bank>Unknown</issuing-bank> <country-of-issuance>Unknown</country-of-issuance> <product-id>Unknown</product-id> <venmo-sdk type=\"boolean\">false</venmo-sdk> </credit-card> <apple-pay> <prepaid>No</prepaid> <healthcare>Unknown</healthcare> <debit>No</debit> <durbin-regulated>Unknown</durbin-regulated> <commercial>No</commercial> <payroll>Unknown</payroll> <issuing-bank>GenericBank</issuing-bank> <country-of-issuance>GCR</country-of-issuance> <product-id>Unknown</product-id> <bin>411111</bin> <card-type>Apple Pay - GenericCard</card-type> <last-4>1234</last-4> <expiration-month>12</expiration-month> <expiration-year>2028</expiration-year> <image-url>https://assets.braintreegateway.com/payment_method_logo/apple_pay.png?environment=production</image-url> <payment-instrument-name>Card 1234</payment-instrument-name> <source-description>Card 1234</source-description> </apple-pay> <status-history type=\"array\"> <status-event> <timestamp type=\"datetime\">2024-11-20T12:36:54Z</timestamp> <status>authorized</status> <amount>57.71</amount> <transaction-source>api</transaction-source> </status-event> </status-history> <subscription></subscription> <add-ons type=\"array\"></add-ons> <discounts type=\"array\"></discounts> <descriptor></descriptor> <recurring type=\"boolean\">false</recurring> <channel></channel> <disbursement-details></disbursement-details> <disputes type=\"array\"></disputes> <authorization-adjustments type=\"array\"></authorization-adjustments> <payment-instrument-type>generic_card</payment-instrument-type> <processor-settlement-response-code></processor-settlement-response-code> <processor-settlement-response-text></processor-settlement-response-text> <network-transaction-id>123456789012345</network-transaction-id> <processor-response-type>approved</processor-response-type> <authorization-expires-at type=\"datetime\">2024-11-27T12:36:54Z</authorization-expires-at> <retry-ids type=\"array\"></retry-ids> <retried type=\"boolean\">false</retried> <refund-global-ids type=\"array\"></refund-global-ids> <partial-settlement-transaction-global-ids type=\"array\"></partial-settlement-transaction-global-ids> <global-id>generic_global_id</global-id> <retry-global-ids type=\"array\"></retry-global-ids> <retrieval-reference-number>123456789012345</retrieval-reference-number> <installments type=\"array\"></installments> <refunded-installments type=\"array\"></refunded-installments> <merchant-address></merchant-address> <pin-verified type=\"boolean\">false</pin-verified> <payment-receipt> <id>bfraj39q</id> <global-id>generic_global_id</global-id> <amount>57.71</amount> <currency-iso-code>USD</currency-iso-code> <processor-response-code>1000</processor-response-code> <processor-response-text>Approved</processor-response-text> <processor-authorization-code>123456</processor-authorization-code> <merchant-address></merchant-address> <type>sale</type> <pin-verified type=\"boolean\">false</pin-verified> </payment-receipt> </transaction>"
            ]
          }
        }
      },
      "co-funding-summary": {
        "type": "object",
        "required": [
          "funder_public_id",
          "receiver_public_id",
          "amount",
          "currency",
          "reference",
          "status"
        ],
        "properties": {
          "funder_public_id": {
            "type": "string",
            "description": "Public merchant ID of the merchant funding the payment.",
            "examples": [
              "merchant_12345"
            ]
          },
          "receiver_public_id": {
            "type": "string",
            "description": "Public merchant ID of the merchant receiving the funding.",
            "examples": [
              "merchant_67890"
            ]
          },
          "amount": {
            "type": "integer",
            "format": "int64",
            "description": "Amount being funded in the smallest currency unit (cents for USD).",
            "examples": [
              1000
            ]
          },
          "currency": {
            "type": "string",
            "description": "Currency code of the co-funding amount.",
            "pattern": "^[A-Z]{3}$",
            "examples": [
              "USD"
            ]
          },
          "reference": {
            "type": "string",
            "description": "Idempotency reference for this co-funding transfer.",
            "examples": [
              "cof_12345_uuid"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "submitted",
              "funded"
            ],
            "description": "Status of the co-funding transfer. 'pending' = created but not yet queued for funding, 'submitted' = queued in funding batch, 'funded' = settled.",
            "examples": [
              "pending"
            ]
          }
        }
      },
      "payment-response-pending": {
        "type": "object",
        "required": [
          ".tag",
          "status",
          "action",
          "url"
        ],
        "properties": {
          ".tag": {
            "type": "string",
            "enum": [
              "pending"
            ],
            "x-order": 0,
            "examples": [
              "pending"
            ]
          },
          "id": {
            "type": "string",
            "format": "id",
            "x-order": 1,
            "examples": [
              "iKv7t5bgt1gg"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "awaiting_user_confirmation"
            ],
            "examples": [
              "awaiting_user_confirmation"
            ]
          },
          "action": {
            "type": "string",
            "enum": [
              "redirect"
            ],
            "examples": [
              "redirect"
            ]
          },
          "url": {
            "type": "string",
            "format": "url",
            "examples": [
              "https://www.example.com/payments/finalize"
            ]
          }
        }
      },
      "payment-response-three-ds-required": {
        "type": "object",
        "required": [
          ".tag",
          "step_up_url",
          "jwt_payload"
        ],
        "properties": {
          ".tag": {
            "type": "string",
            "enum": [
              "three_ds_required"
            ],
            "examples": [
              "three_ds_required"
            ]
          },
          "id": {
            "type": "string",
            "format": "id",
            "x-order": 1,
            "examples": [
              "iKv7t5bgt1gg"
            ]
          },
          "step_up_url": {
            "type": "string",
            "format": "url",
            "examples": [
              "https://www.example.com/payments/finalize"
            ]
          },
          "jwt_payload": {
            "type": "string",
            "examples": [
              "eyJ0cmFuc"
            ]
          }
        }
      },
      "error": {
        "type": "object",
        "required": [
          ".tag",
          "message"
        ],
        "properties": {
          ".tag": {
            "type": "string",
            "enum": [
              "unauthorized",
              "forbidden",
              "unprocessable_request",
              "not_found"
            ],
            "description": "The type of error returned",
            "examples": [
              "unprocessable_request"
            ]
          },
          "message": {
            "type": "string",
            "description": "A human-readable error message, which might include information specific to the request that was made.",
            "examples": [
              "We were unable to process your request."
            ]
          }
        }
      },
      "field-error": {
        "type": "object",
        "description": "An error that pertains to validation of a specific field in the request.",
        "required": [
          ".tag",
          "message",
          "field"
        ],
        "properties": {
          ".tag": {
            "type": "string",
            "enum": [
              "invalid_input_parameter"
            ],
            "description": "The type of error returned",
            "examples": [
              "invalid_input_parameter"
            ]
          },
          "message": {
            "type": "string",
            "description": "A human-readable error message, which might include information specific to the request that was made.",
            "examples": [
              "We were unable to process your request."
            ]
          },
          "field": {
            "type": "string",
            "description": "The field (in its hierarchical form) that is failing validation.",
            "examples": [
              "address.phone"
            ]
          }
        }
      }
    },
    "examples": {
      "payment-response-finalized": {
        "summary": "The payment is final and a transaction record has been created",
        "value": {
          ".tag": "finalized",
          "id": "iKv7t5bgt1gg",
          "status": "success",
          "transaction": {
            "reference": "OBYG-X1PX-FN55",
            "authorizations": [
              {
                "processor_reference": "123456789XYZ"
              }
            ]
          }
        }
      }
    },
    "responses": {
      "response-4xx": {
        "description": "An error has occurred, and further details are contained in the response",
        "content": {
          "application/json": {
            "schema": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/error"
                },
                {
                  "$ref": "#/components/schemas/field-error"
                }
              ]
            }
          }
        }
      },
      "response-default": {
        "description": "An error has occurred, and no further details are provided (e.g. 5xx errors)"
      }
    },
    "securitySchemes": {
      "api-key": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      },
      "oauth": {
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "/v1/oauth/authorize",
            "refreshUrl": "/v1/oauth/token",
            "tokenUrl": "/v1/oauth/token",
            "scopes": {
              "bolt.account.manage": "This scope grants permissions to perform read/edit/delete actions on Bolt Account data",
              "bolt.account.view": "This scope grants permissions to perform read only actions on Bolt Account data",
              "openid": "This scope grants permissions that enable Bolt Single Sign-On (SSO) by granting a JSON Web Token (JWT) that stores account data."
            }
          }
        },
        "type": "oauth2"
      }
    }
  }
}
```