{
  "info": {
    "name": "Teyra Pay API",
    "description": "Every request of the Teyra Pay public `/v1` API.\n\n1. Set the collection variables **baseUrl** (`https://api.teyra.co`, or `http://localhost:4000` for a local Core) and **secretKey** (`sk_test_…`). Use a test key.\n2. Run **Payments → Create a payment**. Its id is saved to `{{paymentId}}` and reused by the other requests.\n\nAuthentication is `Authorization: Bearer {{secretKey}}` on every request. A collection pre-request script adds a fresh `Idempotency-Key` header to each POST that does not set one. Set the header yourself and resend to see the idempotent replay.\n\nMoney is an integer in minor units (`1500` = 1.500 KWD). Docs: https://docs.teyra.co",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json",
    "version": "1.0.0"
  },
  "auth": {
    "type": "bearer",
    "bearer": [
      {
        "key": "token",
        "value": "{{secretKey}}",
        "type": "string"
      }
    ]
  },
  "event": [
    {
      "listen": "prerequest",
      "script": {
        "type": "text/javascript",
        "exec": [
          "// Add a unique Idempotency-Key to every POST that does not already have one.",
          "if (pm.request.method === 'POST' && !pm.request.headers.has('Idempotency-Key')) {",
          "  const key = pm.variables.replaceIn('{{$guid}}');",
          "  pm.request.headers.add({ key: 'Idempotency-Key', value: key });",
          "  pm.collectionVariables.set('lastIdempotencyKey', key);",
          "}"
        ]
      }
    }
  ],
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://api.teyra.co",
      "type": "string"
    },
    {
      "key": "secretKey",
      "value": "sk_test_replace_me",
      "type": "string"
    },
    {
      "key": "paymentId",
      "value": "",
      "type": "string"
    },
    {
      "key": "refundId",
      "value": "",
      "type": "string"
    },
    {
      "key": "paymentLinkId",
      "value": "",
      "type": "string"
    },
    {
      "key": "webhookEndpointId",
      "value": "",
      "type": "string"
    },
    {
      "key": "nextCursor",
      "value": "",
      "type": "string"
    },
    {
      "key": "lastIdempotencyKey",
      "value": "",
      "type": "string"
    }
  ],
  "item": [
    {
      "name": "Payments",
      "item": [
        {
          "name": "Create a payment",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "pm.test(\"Status is 2xx\", () => pm.expect(pm.response.code).to.be.within(200, 299));",
                  "const body = pm.response.json();",
                  "if (body && body.id) pm.collectionVariables.set('paymentId', body.id);"
                ]
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"amount\": 12500,\n  \"currency\": \"KWD\",\n  \"return_url\": \"https://shop.example.com/thanks\",\n  \"description\": \"Order #1042\",\n  \"reference\": \"1042\",\n  \"customer\": {\n    \"name\": \"Sara Ali\",\n    \"email\": \"sara@example.com\",\n    \"phone\": \"+96550000000\"\n  },\n  \"language\": \"en\",\n  \"metadata\": {\n    \"order_id\": \"1042\"\n  },\n  \"expires_in_minutes\": 60\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "url": {
              "raw": "{{baseUrl}}/v1/payments",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "payments"
              ]
            },
            "description": "Creates a payment and returns its hosted `checkout_url`. Send the customer there. Required: `amount`, `currency`, `return_url`."
          },
          "response": []
        },
        {
          "name": "Retrieve a payment",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "pm.test(\"Status is 2xx\", () => pm.expect(pm.response.code).to.be.within(200, 299));"
                ]
              }
            }
          ],
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/payments/{{paymentId}}",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "payments",
                "{{paymentId}}"
              ]
            }
          },
          "response": []
        },
        {
          "name": "List payments",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "pm.test(\"Status is 200\", () => pm.response.to.have.status(200));",
                  "pm.test(\"Is a list\", () => pm.expect(pm.response.json()).to.have.keys(\"data\", \"has_more\", \"next_cursor\"));",
                  "const { next_cursor } = pm.response.json();",
                  "pm.collectionVariables.set('nextCursor', next_cursor || '');"
                ]
              }
            }
          ],
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/payments?limit=20",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "payments"
              ],
              "query": [
                {
                  "key": "status",
                  "value": "succeeded",
                  "description": "requires_payment | processing | succeeded | failed | canceled | expired",
                  "disabled": true
                },
                {
                  "key": "reference",
                  "value": "1042",
                  "disabled": true
                },
                {
                  "key": "created_gte",
                  "value": "2026-10-01T00:00:00Z",
                  "disabled": true
                },
                {
                  "key": "created_lte",
                  "value": "2026-10-31T23:59:59Z",
                  "disabled": true
                },
                {
                  "key": "limit",
                  "value": "20",
                  "description": "1–100, default 20"
                },
                {
                  "key": "cursor",
                  "value": "{{nextCursor}}",
                  "description": "`next_cursor` from the previous page",
                  "disabled": true
                }
              ]
            },
            "description": "Newest first. Pass `cursor` = `next_cursor` from the previous page to continue."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Refunds",
      "item": [
        {
          "name": "Refund a payment",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "pm.test(\"Status is 2xx\", () => pm.expect(pm.response.code).to.be.within(200, 299));",
                  "const body = pm.response.json();",
                  "if (body && body.id) pm.collectionVariables.set('refundId', body.id);"
                ]
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"amount\": 5000,\n  \"reason\": \"requested_by_customer\"\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "url": {
              "raw": "{{baseUrl}}/v1/payments/{{paymentId}}/refunds",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "payments",
                "{{paymentId}}",
                "refunds"
              ]
            },
            "description": "Omit `amount` to refund what is left. Only succeeded payments can be refunded."
          },
          "response": []
        },
        {
          "name": "Retrieve a refund",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "pm.test(\"Status is 2xx\", () => pm.expect(pm.response.code).to.be.within(200, 299));"
                ]
              }
            }
          ],
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/refunds/{{refundId}}",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "refunds",
                "{{refundId}}"
              ]
            }
          },
          "response": []
        },
        {
          "name": "List refunds",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "pm.test(\"Status is 200\", () => pm.response.to.have.status(200));",
                  "pm.test(\"Is a list\", () => pm.expect(pm.response.json()).to.have.keys(\"data\", \"has_more\", \"next_cursor\"));",
                  "const { next_cursor } = pm.response.json();",
                  "pm.collectionVariables.set('nextCursor', next_cursor || '');"
                ]
              }
            }
          ],
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/refunds?limit=20",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "refunds"
              ],
              "query": [
                {
                  "key": "payment_id",
                  "value": "{{paymentId}}",
                  "disabled": true
                },
                {
                  "key": "limit",
                  "value": "20",
                  "description": "1–100, default 20"
                },
                {
                  "key": "cursor",
                  "value": "{{nextCursor}}",
                  "description": "`next_cursor` from the previous page",
                  "disabled": true
                }
              ]
            }
          },
          "response": []
        }
      ]
    },
    {
      "name": "Payment links",
      "item": [
        {
          "name": "Create a payment link",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "pm.test(\"Status is 2xx\", () => pm.expect(pm.response.code).to.be.within(200, 299));",
                  "const body = pm.response.json();",
                  "if (body && body.id) pm.collectionVariables.set('paymentLinkId', body.id);"
                ]
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"amount\": 5000,\n  \"currency\": \"KWD\",\n  \"description\": \"Consultation\",\n  \"single_use\": false,\n  \"expires_at\": null\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "url": {
              "raw": "{{baseUrl}}/v1/payment-links",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "payment-links"
              ]
            }
          },
          "response": []
        },
        {
          "name": "Retrieve a payment link",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "pm.test(\"Status is 2xx\", () => pm.expect(pm.response.code).to.be.within(200, 299));"
                ]
              }
            }
          ],
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/payment-links/{{paymentLinkId}}",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "payment-links",
                "{{paymentLinkId}}"
              ]
            }
          },
          "response": []
        },
        {
          "name": "List payment links",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "pm.test(\"Status is 200\", () => pm.response.to.have.status(200));",
                  "pm.test(\"Is a list\", () => pm.expect(pm.response.json()).to.have.keys(\"data\", \"has_more\", \"next_cursor\"));",
                  "const { next_cursor } = pm.response.json();",
                  "pm.collectionVariables.set('nextCursor', next_cursor || '');"
                ]
              }
            }
          ],
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/payment-links?limit=20",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "payment-links"
              ],
              "query": [
                {
                  "key": "limit",
                  "value": "20",
                  "description": "1–100, default 20"
                },
                {
                  "key": "cursor",
                  "value": "{{nextCursor}}",
                  "description": "`next_cursor` from the previous page",
                  "disabled": true
                }
              ]
            }
          },
          "response": []
        },
        {
          "name": "Deactivate a payment link",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "pm.test(\"Status is 2xx\", () => pm.expect(pm.response.code).to.be.within(200, 299));"
                ]
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/payment-links/{{paymentLinkId}}/deactivate",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "payment-links",
                "{{paymentLinkId}}",
                "deactivate"
              ]
            }
          },
          "response": []
        }
      ]
    },
    {
      "name": "Deposits",
      "item": [
        {
          "name": "List deposits",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "pm.test(\"Status is 200\", () => pm.response.to.have.status(200));",
                  "pm.test(\"Is a list\", () => pm.expect(pm.response.json()).to.have.keys(\"data\", \"has_more\", \"next_cursor\"));",
                  "const { next_cursor } = pm.response.json();",
                  "pm.collectionVariables.set('nextCursor', next_cursor || '');"
                ]
              }
            }
          ],
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/deposits?limit=20",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "deposits"
              ],
              "query": [
                {
                  "key": "limit",
                  "value": "20",
                  "description": "1–100, default 20"
                },
                {
                  "key": "cursor",
                  "value": "{{nextCursor}}",
                  "description": "`next_cursor` from the previous page",
                  "disabled": true
                }
              ]
            }
          },
          "response": []
        }
      ]
    },
    {
      "name": "Webhook endpoints",
      "item": [
        {
          "name": "Create a webhook endpoint",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "pm.test(\"Status is 2xx\", () => pm.expect(pm.response.code).to.be.within(200, 299));",
                  "const body = pm.response.json();",
                  "if (body && body.id) pm.collectionVariables.set('webhookEndpointId', body.id);"
                ]
              }
            }
          ],
          "request": {
            "method": "POST",
            "header": [
              {
                "key": "Content-Type",
                "value": "application/json"
              }
            ],
            "body": {
              "mode": "raw",
              "raw": "{\n  \"url\": \"https://shop.example.com/hooks/teyra\",\n  \"events\": [\n    \"payment.succeeded\",\n    \"payment.failed\",\n    \"refund.succeeded\"\n  ]\n}",
              "options": {
                "raw": {
                  "language": "json"
                }
              }
            },
            "url": {
              "raw": "{{baseUrl}}/v1/webhook-endpoints",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "webhook-endpoints"
              ]
            },
            "description": "The response includes the signing `secret` (`whsec_…`) once. Store it to verify `Teyra-Signature`."
          },
          "response": []
        },
        {
          "name": "List webhook endpoints",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "pm.test(\"Status is 200\", () => pm.response.to.have.status(200));",
                  "pm.test(\"Is a list\", () => pm.expect(pm.response.json()).to.have.keys(\"data\", \"has_more\", \"next_cursor\"));",
                  "const { next_cursor } = pm.response.json();",
                  "pm.collectionVariables.set('nextCursor', next_cursor || '');"
                ]
              }
            }
          ],
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/webhook-endpoints",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "webhook-endpoints"
              ]
            }
          },
          "response": []
        },
        {
          "name": "Delete a webhook endpoint",
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "pm.test(\"Status is 2xx\", () => pm.expect(pm.response.code).to.be.within(200, 299));"
                ]
              }
            }
          ],
          "request": {
            "method": "DELETE",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/v1/webhook-endpoints/{{webhookEndpointId}}",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "v1",
                "webhook-endpoints",
                "{{webhookEndpointId}}"
              ]
            }
          },
          "response": []
        }
      ]
    }
  ]
}