---
agentTools:
  projectIndex: https://payment-orchestrator.readme.io/llms.txt
---

# Authorize Payment

Creates a Payment Transaction in the system and authorizes it through the resulting third party receiver.

# OpenAPI definition

```json
{
  "openapi": "3.0.0",
  "info": {
    "version": "v1",
    "title": "Payment API",
    "description": "The Payment API is a service that allows merchants to connect with multiple payment receivers through a single API call.\n"
  },
  "servers": [
    {
      "url": "http://sandbox-planet-oapi-269696318.eu-central-1.elb.amazonaws.com:8080/api",
      "description": "Payment API - Staging"
    }
  ],
  "security": [
    {
      "api-key": []
    }
  ],
  "tags": [
    {
      "name": "Payments",
      "description": "Manage Payments"
    }
  ],
  "paths": {
    "/v1/payments": {
      "post": {
        "tags": [
          "Payments"
        ],
        "summary": "Authorize Payment",
        "operationId": "authorize-payment",
        "description": "Creates a Payment Transaction in the system and authorizes it through the resulting third party receiver.\n",
        "responses": {
          "201": {
            "description": "The payment was authorized successfully and a payment transaction was created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentTransaction"
                }
              }
            },
            "headers": {
              "Location": {
                "schema": {
                  "type": "string",
                  "format": "uri",
                  "description": "The location that can be accessed to retrieve the authorized payment transaction."
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "500": {
            "$ref": "#/components/responses/InternalServerError"
          }
        },
        "parameters": [
          {
            "in": "header",
            "name": "x-cc-merchant-id",
            "required": true,
            "description": "The identifier of the merchant making the request",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "pci-proxy-api-key",
            "required": true,
            "description": "The API Key to use in PCI-Proxy requests",
            "schema": {
              "type": "string"
            }
          },
          {
            "in": "header",
            "name": "pci-proxy-password",
            "required": true,
            "description": "The password to use in PCI-Proxy requests",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuthorizePaymentRequest"
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "responses": {
      "BadRequest": {
        "description": "The request is invalid. The specific reason is returned in the response body.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "The requester is not authorized to access the resource.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        },
        "headers": {
          "WWW_Authenticate": {
            "schema": {
              "type": "string"
            }
          }
        }
      },
      "InternalServerError": {
        "description": "The request is valid but the server could not process it. The specific reason is returned in the response body.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      }
    },
    "securitySchemes": {
      "api-key": {
        "type": "apiKey",
        "name": "API-KEY",
        "in": "header",
        "description": "The API Key to authorize requests."
      }
    },
    "schemas": {
      "Problem": {
        "type": "object",
        "description": "An explanation of the problem that occurred when processing a request [RFC7807].",
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "description": "A URI reference [RFC3986] that identifies the problem type.  This specification encourages that, when dereferenced, it provide human-readable documentation for the problem type (e.g., using HTML [W3C.REC-html5-20141028]).  When this member is not present, its value is assumed to be \"about:blank\".\n",
            "example": "/problems/validation-failed"
          },
          "title": {
            "type": "string",
            "description": "A short, human-readable summary of the problem type.  It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization (e.g., using proactive content negotiation; see [RFC7231], Section 3.4).",
            "example": "The validation for the request has produced errors."
          },
          "status": {
            "type": "integer",
            "description": "The HTTP status code ([RFC7231], Section 6) generated by the origin server for this occurrence of the problem. Optional field.",
            "example": 400
          },
          "detail": {
            "type": "string",
            "description": "A human-readable explanation specific to this occurrence of the problem.",
            "example": "The validation of the request failed on field(s) 'A'."
          },
          "errors": {
            "type": "array",
            "nullable": true,
            "description": "A collection of all errors that occurred when processing the request.",
            "items": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "description": "Represents a single error within the application.",
        "properties": {
          "code": {
            "type": "string",
            "nullable": true,
            "description": "The unique error code.",
            "example": "V1234"
          },
          "message": {
            "type": "string",
            "description": "A human-readable message that states the error.",
            "example": "Field A value must be between 1 and 20."
          }
        }
      },
      "ReceiverId": {
        "type": "string",
        "nullable": false,
        "maxLength": 50,
        "description": "The receiver identifier."
      },
      "AuthorizePaymentRequest": {
        "type": "object",
        "nullable": false,
        "required": [
          "reference",
          "amount",
          "currency",
          "merchantApiKey",
          "workflowIdentifier",
          "paymentMethod"
        ],
        "properties": {
          "reference": {
            "type": "string",
            "nullable": false
          },
          "paymentAuthenticationId": {
            "type": "integer",
            "format": "int64",
            "nullable": true
          },
          "amount": {
            "$ref": "#/components/schemas/Amount"
          },
          "currency": {
            "type": "string",
            "nullable": false
          },
          "merchantApiKey": {
            "type": "string",
            "nullable": false
          },
          "workflowIdentifier": {
            "type": "string",
            "format": "uuid",
            "nullable": false
          },
          "paymentMethod": {
            "$ref": "#/components/schemas/PaymentMethod"
          }
        }
      },
      "PaymentMethod": {
        "type": "object",
        "nullable": false,
        "required": [
          "type"
        ],
        "properties": {
          "type": {
            "$ref": "#/components/schemas/PaymentMethodType"
          }
        },
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "Card": "#/components/schemas/CardPaymentMethod"
          }
        }
      },
      "PaymentMethodType": {
        "type": "string",
        "nullable": false,
        "enum": [
          "Card"
        ]
      },
      "CardPaymentMethod": {
        "allOf": [
          {
            "$ref": "#/components/schemas/PaymentMethod"
          },
          {
            "type": "object",
            "required": [
              "cardNumber",
              "cvv",
              "expiryMonth",
              "expiryYear",
              "cardHolderName"
            ],
            "properties": {
              "cardNumber": {
                "type": "string",
                "nullable": false
              },
              "cvv": {
                "type": "string",
                "nullable": false
              },
              "expiryMonth": {
                "type": "string",
                "nullable": false
              },
              "expiryYear": {
                "type": "string",
                "nullable": false
              },
              "cardHolderName": {
                "type": "string",
                "nullable": false
              }
            }
          }
        ]
      },
      "PaymentTransaction": {
        "type": "object",
        "nullable": false,
        "required": [
          "id",
          "reference",
          "amount",
          "capturedAmount",
          "currency",
          "status",
          "createdAt",
          "updatedAt",
          "receiverId",
          "executionId"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/PaymentId"
          },
          "reference": {
            "type": "string",
            "nullable": false
          },
          "paymentAuthenticationId": {
            "type": "integer",
            "format": "int64",
            "nullable": true
          },
          "amount": {
            "$ref": "#/components/schemas/Amount"
          },
          "capturedAmount": {
            "$ref": "#/components/schemas/Amount"
          },
          "currency": {
            "type": "string",
            "nullable": false
          },
          "status": {
            "type": "string",
            "nullable": false
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "nullable": false
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "nullable": false
          },
          "operations": {
            "type": "array",
            "nullable": true,
            "items": {
              "$ref": "#/components/schemas/PaymentOperation"
            }
          },
          "receiverId": {
            "$ref": "#/components/schemas/ReceiverId"
          },
          "executionId": {
            "$ref": "#/components/schemas/ExecutionId"
          }
        }
      },
      "Amount": {
        "type": "number",
        "format": "double",
        "nullable": false
      },
      "PaymentId": {
        "type": "string",
        "format": "uuid",
        "nullable": false,
        "description": "The payment transaction identifier."
      },
      "ExecutionId": {
        "type": "string",
        "format": "uuid",
        "description": "The workflow execution identifier."
      },
      "PaymentOperation": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string"
          },
          "success": {
            "type": "boolean"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time"
          },
          "attributes": {
            "type": "array",
            "nullable": true,
            "items": {
              "$ref": "#/components/schemas/Attribute"
            }
          }
        }
      },
      "Attribute": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "value": {
            "type": "string"
          }
        }
      }
    }
  },
  "x-readme": {
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "_id": {
    "buffer": {
      "0": 100,
      "1": 99,
      "2": 95,
      "3": 209,
      "4": 224,
      "5": 111,
      "6": 134,
      "7": 6,
      "8": 133,
      "9": 199,
      "10": 135,
      "11": 133
    }
  }
}
```