{"openapi":"3.0.0","info":{"title":"Authorization Service","description":"The only cross-border payments API with payment coverage across developed and emerging markets. Get the tools, resources, and guides you need to build a great cross-border payment experience for your business. Let's help you reach your growth goals.\n","version":"1.0.0","license":{"name":"","url":" "}},"tags":[{"name":"Authorization","description":" "},{"name":"Webhooks","description":"Real-time events from VertoFX sent to your server."}],"servers":[{"url":"https://api-v3-sandbox.vertofx.com","description":"For Legacy (v2.1 and v2.2) APIs"}],"x-readme":{"samples-languages":["shell","node","ruby","javascript","python","csharp","php"]},"security":[{"bearerAuth":[]}],"x-webhooks":{"PAYMENT_STATUS_CHANGE":{"post":{"tags":["Webhooks"],"summary":"Payment status change","operationId":"PAYMENT_STATUS_CHANGE","description":"Triggered when a payment status is updated.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentStatusWebhook"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"FX_STATUS_CHANGE":{"post":{"tags":["Webhooks"],"summary":"FX order status change","operationId":"FX_STATUS_CHANGE","description":"Triggered when the status of an FX order is updated.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FXStatusWebhook"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}},"BENEFICIARY_STATUS_CHANGE":{"post":{"tags":["Webhooks"],"summary":"Beneficiary status change","operationId":"BENEFICIARY_STATUS_CHANGE","description":"Triggered when a beneficiary's verification or approval status is updated.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BeneficiaryStatusWebhook"}}}},"responses":{"200":{"description":"Webhook received successfully"}}}}},"paths":{"/users/login":{"post":{"security":[{}],"tags":["Authorization"],"summary":"Login","operationId":"login","description":"## Authorization\n\nThe Authorization service contains only one API, which is the Login API, to authenticate a user in the VertoFX platform.\n\nThe Login service requires you to send your authorization request using `clientId` and `apiKey`.\n\nIf you don't know your `clientId` and `apiKey`, please refer to [Authentication](https://vertofx-csay.readme.io/docs/authentication).\n\nAlso, you need to make sure that the `mode` parameter is set to `apiKey`.\n\nIn response to your request, you'll be provided with a `token value`.\n\n> ℹ️\n  You need to add this `token value` in the `Authorization header` using **Bearer scheme** to access all other endpoints.\n\n> ℹ️\n  Each **Login** API request generates a new `token value` which is valid for **60 minutes**. Therefore, before generating a new `token value` it is recommended to use an existing `token value` until it expires.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"clientId":{"type":"string","description":"A unique 28-digit alpha-numeric identifier assigned to the client generated by the VertoFx portal. To know more, click [Authentication](https://vertofx-csay.readme.io/docs/authentication).","example":"YOUR_CLIENT_ID"},"apiKey":{"type":"string","description":"The key generated to access the API. To know more, click [Authentication](https://vertofx-csay.readme.io/docs/authentication).","example":"YOUR_API_KEY"},"mode":{"type":"string","description":"Pass the `mode` as `apiKey` for us to know the request comes from an API customer.","example":"apiKey"}},"required":["clientId","apiKey","mode"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"A boolean flag indicating whether the authorization was successful.\n\nThis field returns `true` if the operation was completed successfully, and `false` otherwise.\n\nIt helps in quickly identifying the status of the request.\n"},"token":{"type":"string","description":"An authentication token that provides user a secure and standardized way to authentication when consuming other APIs. This `token` value is valid for **60 minutes**. You need to add this value in the header parameter to authenticate other APIs."},"companyId":{"type":"string","description":"Indicates the unique identifier assigned to a company within the system."}}},"example":{"success":true,"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uSWQiOiI0NjI1YWVkOC0xMmZmLTIzMmQtZWE0OC0yYWYzMjllMGVjNTEiLCJsb2dpbk1vZGUiOiJhcGlLZXkiLCJpZCI6NTI2LCJjb21wYW55SWQiOjUyNSwicHJvZmlsZUlkIjo1MjYsInVzZXJSZWNvcmRJZCI6MTQ4LCJyb2xlIjoiTk9STUFMX0NMSUVOVCIsInJvbGVOYW1lIjoiTXVsdGkgVXNlciIsInJlZmVyZW5jZSI6IlZVLTI5MTEyMDIyLTE2MS1VMSIsInByb2ZpbGVSZWZlcmVuY2UiOiJWVS0yOTExMjAyMi0xNjEtVTEiLCJjb21wYW55UmVmZXJlbmNlIjoiVlUtMjkxMTIwMjItMTYxIiwiY29tcGFueU5hbWUiOiJIZXlQYXkiLCJyYXRlTGltaXQiOjIwMDAsImlhdCI6MTcyMTEyMDIwNywiZXhwIjoxNzIxMTIzODA3fQ.example-signature-not-valid","companyId":"1234"}}}},"400":{"$ref":"#/components/responses/BadRequest-400"},"401":{"$ref":"#/components/responses/Unauthorized-401"},"500":{"$ref":"#/components/responses/InternalServerError-500"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Example:\n> Authorization: Bearer <i>token</i>\n"}},"responses":{"BadRequest-400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","description":"Displays HTTP error code.\n"},"message":{"type":"string","description":"Displays error message."}}}}}},"Unauthorized-401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","description":"The request lacks valid authentication credentials. Please ensure you have the necessary authorization tokens and try again.","properties":{"code":{"type":"number","description":"Displays HTTP error code.\n"},"message":{"type":"string","description":"Displays error message."}}}}}},"InternalServerError-500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"number","description":"Displays HTTP error code.\n"},"message":{"type":"string","description":"Displays error message."}}}}}}},"schemas":{"PaymentStatusWebhook":{"type":"object","required":["paymentId","oldStatus","newStatus","updatedAt"],"properties":{"paymentId":{"type":"string","description":"Unique ID of the payment whose status changed.","example":"pm_456789"},"oldStatus":{"type":"string","description":"The previous status of the payment.","example":"Requested"},"newStatus":{"type":"string","description":"The updated status of the payment.","example":"Completed"},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp of the status update.","example":"2025-03-21T10:15:30Z"}}},"FXStatusWebhook":{"type":"object","required":["fxOrderId","oldStatus","newStatus","updatedAt"],"properties":{"fxOrderId":{"type":"string","description":"Unique identifier for the FX order.","example":"fx_983745"},"oldStatus":{"type":"string","description":"The previous status of the FX order.","example":"Pending"},"newStatus":{"type":"string","description":"The updated status of the FX order.","example":"Completed"},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp of the status update.","example":"2025-03-21T11:00:00Z"}}},"BeneficiaryStatusWebhook":{"type":"object","required":["beneficiaryId","oldStatus","newStatus","updatedAt"],"properties":{"beneficiaryId":{"type":"string","description":"Unique identifier of the beneficiary.","example":"bnf_102938"},"oldStatus":{"type":"string","description":"The previous verification or approval status.","example":"Pending Verification"},"newStatus":{"type":"string","description":"The new status after an update.","example":"Approved"},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp of the status update.","example":"2025-03-21T09:45:00Z"}}}}}}