# Request Payment

This documentation provides detailed information about the Reach Pay API, focusing on the checkout process. It covers the API endpoint, request and response structures, field definitions, and potential error messages. This guide is intended for developers integrating the Reach Pay service into their applications, ensuring seamless payment processing and accurate transaction tracking.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "reach-pay-api-documentation",
    "version": "1.0"
  },
  "servers": [
    {
      "url": "https://api.reachware.com"
    }
  ],
  "security": [
    {}
  ],
  "paths": {
    "/pay/RequestPayment": {
      "post": {
        "summary": "Request Payment",
        "description": "This documentation provides detailed information about the Reach Pay API, focusing on the checkout process. It covers the API endpoint, request and response structures, field definitions, and potential error messages. This guide is intended for developers integrating the Reach Pay service into their applications, ensuring seamless payment processing and accurate transaction tracking.",
        "operationId": "reach-pay-checkout",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "client_id",
                  "order_id",
                  "payment_id",
                  "amount",
                  "return_url"
                ],
                "properties": {
                  "client_id": {
                    "type": "string",
                    "description": "Unique identifier for the client. This ID is used to associate the transaction with a specific client in the system.",
                    "default": "clientTest"
                  },
                  "location_id": {
                    "type": "string",
                    "description": "The identifier for the location where the transaction is taking place. This field is crucial for multi-location clients to track transactions accurately.",
                    "default": "3ac-4d6e-4230-9b9c-6cd01b96350d"
                  },
                  "order_id": {
                    "type": "string",
                    "description": "A unique identifier for the order associated with the payment. This ID is used to link the payment to the correct order.",
                    "default": "ca73caca711111113s1a13ca71111121"
                  },
                  "payment_id": {
                    "type": "string",
                    "description": "A unique identifier for the payment transaction. This field ensures that each payment is uniquely tracked and managed.",
                    "default": "ca7111111a59"
                  },
                  "amount": {
                    "type": "number",
                    "description": "The total amount to be paid. This field should include the currency in the relevant context (e.g., SAR))",
                    "default": 33,
                    "format": "float"
                  },
                  "return_url": {
                    "type": "string",
                    "description": "This field will activate the webhook, regardless of whether the payment is successful or fails.",
                    "default": "https://webhook.site/d8420c66-d8c0-49ea-b858-fa29dfafba9b"
                  },
                  "card_token": {
                    "type": "string",
                    "description": "A token representing the customer's card information, used for processing the payment. This field is optional, depending on whether the payment is made using a stored card.",
                    "default": "token_R5BHVKrftwbnaVmw95hxZjMjJZ"
                  },
                  "redirect_url": {
                    "type": "string",
                    "description": "The URL of the customer's webpage to which the redirection will occur upon completion of the operation. If the key is not supplied, the redirection will default to the Reachpay results page.",
                    "default": "https://www.reachware.com"
                  },
                  "lang": {
                    "type": "string",
                    "default": "en"
                  },
                  "card_save": {
                    "type": "string",
                    "default": "false"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "200",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"payment_id\": \"4598521652156\",\n    \"payment_gateway_url\": \"https://api.reachware.com/pay/CheckoutPage?rw_code=03B71D03044118B2260E239B0DA20C76:0A665028A7F950572EA0EE6FBB2EDC7F:CBC6512B2BB89A5AB657F8EA4C707BF1\"\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "payment_id": {
                      "type": "string",
                      "example": "4598521652156"
                    },
                    "payment_gateway_url": {
                      "type": "string",
                      "example": "https://api.reachware.com/pay/CheckoutPage?rw_code=03B71D03044118B2260E239B0DA20C76:0A665028A7F950572EA0EE6FBB2EDC7F:CBC6512B2BB89A5AB657F8EA4C707BF1"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "400",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"error\": true,\n    \"message\": \"return_url is messing\"\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "boolean",
                      "example": true,
                      "default": true
                    },
                    "message": {
                      "type": "string",
                      "example": "return_url is messing"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "404",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"error\": true,\n    \"message\": \"Config not found for id:\"\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "boolean",
                      "example": true,
                      "default": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Config not found for id:"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "500",
            "content": {
              "application/json": {
                "examples": {
                  "Result": {
                    "value": "{\n    \"body\": \"{\\r\\n    \\\"client_id\\\": \\\"clientTest\\\",\\n    \\\"location_id\\\": \\\"3ac-4d6e-4230-9b9b-6cd01b96350d\\\",\\r\\n    \\\"order_id\\\": \\\"ca73caca711111113s1a13ca71111122\\\",\\r\\n    \\\"payment_id\\\": \\\"ca7111111a57\\\",\\r\\n    \\\"amount\\\": 5235,\\r\\n    \\\"return_url\\\": \\\"https://webhook.site/dd4e57f2-79e5-43e6-b915-fba5d398454e?payment_id=ca7111111a57\\\"\\r\\n    \\n}\",\n    \"message\": \"Payment Submitted before\"\n}"
                  }
                },
                "schema": {
                  "type": "object",
                  "properties": {
                    "body": {
                      "type": "string",
                      "example": "{\r\n    \"client_id\": \"clientTest\",\n    \"location_id\": \"3ac-4d6e-4230-9b9b-6cd01b96350d\",\r\n    \"order_id\": \"ca73caca711111113s1a13ca71111122\",\r\n    \"payment_id\": \"ca7111111a57\",\r\n    \"amount\": 5235,\r\n    \"return_url\": \"https://webhook.site/dd4e57f2-79e5-43e6-b915-fba5d398454e?payment_id=ca7111111a57\"\r\n    \n}"
                    },
                    "message": {
                      "type": "string",
                      "example": "Payment Submitted before"
                    }
                  }
                }
              }
            }
          }
        },
        "deprecated": false
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```