{"openapi":"3.0.3","info":{"title":"Payment","version":"1.0","description":"Service responsible for creating and managing payments across Verto and external banks."},"paths":{"/payments/create":{"post":{"tags":["client"],"summary":"Create a payment request","description":"Creates a new payment request based on the specified payment type.\nSupports wallet-to-business transfers, wallet payouts to bank accounts,\nand transfers within wallets. The payment type determines the required\nfields and validation rules applied.","operationId":"create_payment_request","x-atlas-api":true,"x-permission-config":["Client:Make Payment To Account:write","Client:Make Payment To Another Business:write"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardizedPaymentRequest"},"examples":{"walletPayout":{"summary":"Wallet payout to bank account","value":{"paymentType":"WALLET_PAYOUT","sourceWalletId":"12345","sourceAmount":1000.5,"targetAccountId":"67890","purposeId":"1","customPaymentReference":"Invoice payment #12345"}},"walletToBusiness":{"summary":"Wallet to business transfer","value":{"paymentType":"WALLET_TO_BUSINESS","sourceWalletId":"12345","sourceAmount":500,"targetCompanyId":"98765","purposeId":"2"}},"transferWithinWallets":{"summary":"Transfer within wallets","value":{"paymentType":"TRANSFER_WITHIN_WALLETS","sourceWalletId":"12345","sourceAmount":250,"targetWalletId":"67890"}}}}}},"responses":{"201":{"description":"Payment request created successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardizedPaymentResponse"},"example":{"reference":"TO-29072023-114","type":"WALLET_PAYOUT","state":"REQUESTED"}}}},"400":{"description":"Bad Request - Invalid input or validation error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":400,"message":"Invalid payment type or missing required fields"}}}},"401":{"description":"Unauthorized - Authentication required.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":401,"message":"Unauthorized"}}}},"403":{"description":"Forbidden - Insufficient permissions to create payments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":403,"message":"Forbidden"}}}},"500":{"description":"Internal Server Error - An unexpected error occurred on the server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"code":500,"message":"Internal Server Error"}}}}}}},"/transfer":{"post":{"summary":"Initiate a transfer to another wallet or business","x-atlas-api":true,"tags":["client"],"operationId":"transfer_to_another_wallet","x-permission-config":["Client:Make Payment To Account:write","Client:Make Payment To Another Business:write","Admin:Exchange Now:write","Client:At Desired Rate:write","Admin:Exchange Later:write","Client:At Verto Rate:write"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferParams"}}}},"responses":{"200":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransferResponse"}}}}}}},"/payments/{paymentId}":{"get":{"summary":"Retrieve payment details by payment ID","operationId":"get_payment_by_payment_id","x-atlas-api":true,"tags":["client"],"x-permission-config":["Admin:Exchange Now:read","Client:At Desired Rate:read","Admin:Exchange Later:read"],"parameters":[{"name":"paymentId","in":"path","description":"payment identifier","required":true,"schema":{"type":"string","example":"ee7e9602-4dd2-4d02-ae55-bfc527c913ef"}}],"responses":{"200":{"description":"Payment details retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentIdResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"description":"Forbidden - User does not have access to this payment or payment belongs to different company","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Payment not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"$ref":"#/components/responses/ServerError"}}}},"/payments/payment-tracking/{reference}":{"get":{"summary":"Get payment tracking details","description":"Returns the payment tracking details of an FX order or wallet payment, including the MT103, UETR, unique bank reference, and proof of payment.","tags":["client"],"operationId":"get_payment_tracking_detail","x-atlas-api":true,"x-permission-config":["Client:Make Payment To Account:write","Client:Make Payment To Another Business:write","Admin:Exchange Now:write","Client:At Desired Rate:write","Admin:Exchange Later:write","Client:At Verto Rate:write"],"parameters":[{"name":"reference","in":"path","description":"Reference of the FX order or wallet payment.","required":true,"schema":{"type":"string","pattern":"^(TO|EN)-[A-Z0-9-]+$","example":"TO-29072023-A114"}}],"responses":{"200":{"description":"success","content":{"application/json":{"schema":{"type":"object","properties":{"reference":{"type":"string","example":"TO-01012025-A111"},"mt103":{"type":"string","nullable":true,"example":"ABC"},"uetr":{"type":"string","nullable":true,"example":"ABC"},"uniqueBankReference":{"type":"string","nullable":true,"example":"ABC"},"pop":{"type":"string","nullable":true,"description":"Proof of payment value. Falls back to the MT103 or UETR when no document is available.","example":"s3://bucket/proof.pdf"},"type":{"type":"string","nullable":true,"description":"Proof of payment type, in uppercase (for example, PDF, MT103, or UETR).","example":"MT103"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/documents/generate-upload-link":{"post":{"summary":"Generate a link to be used to upload a file.","tags":["generic api"],"operationId":"generate_link_to_upload_file","x-atlas-api":true,"x-permission-config":["Admin:Exchange Now:read","Client:At Desired Rate:read","Admin:Exchange Later:read","Client:At Verto Rate:read"],"parameters":[{"name":"companyId","in":"query","description":"used if user is an admin to map the file path correctly","required":false,"schema":{"type":"string","example":45248}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fileName":{"type":"string","description":"Name of the file with extension","nullable":false,"minLength":5,"maxLength":100},"documentInfo":{"type":"object","description":"Additional document metadata","properties":{"source":{"type":"string","example":"user"},"reference":{"type":"string","example":"TO-29072023-114"},"entity":{"type":"string","example":"order"},"userRecordId":{"type":"integer","example":2669}}}}}}}},"responses":{"200":{"description":"File generated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"link":{"type":"string","description":"An unique link valid for 10 minutes on which clinet can upload their files supported formats are [\"jpeg\", \"jpg\", \"pdf\", \"png\", \"svg\"] and max file size should be 5mb."},"key":{"type":"string","description":"An unique key that client can use in a subsequent API call to link uploaded supporting documents."}}}}}},"400":{"description":"unacceptable request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"a server side error occurred","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/payments/purpose-codes":{"get":{"summary":"List Payment Purpose Codes","description":"Retrieves a list of Payment Purpose Codes based on the provided filters.\nThis endpoint supports filtering by purpose, entity type, and payment direction.","operationId":"list_payment_purpose_codes_v2","x-permission-config":["Client:Make Payment To Account:read","Client:Make Payment To Another Business:read"],"x-atlas-api":true,"tags":["client"],"parameters":[{"name":"id","in":"query","description":"Document type ID or array of IDs. Can be a single ID or a JSON array string\n(e.g., \"[1,2,3]\").","required":false,"schema":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"example":"1"},{"name":"purpose","in":"query","description":"If \"true\", returns only Payment Purpose category types.\nIf \"false\" or omitted, returns all non-Payment Purpose types.","required":false,"schema":{"type":"string","enum":["true","false"]},"example":"false"},{"name":"entityType","in":"query","description":"Filter by entity type (e.g., \"individual\", \"business\").","required":false,"schema":{"type":"string"},"example":"business"},{"name":"paymentDirection","in":"query","description":"Filter by payment direction.","required":false,"schema":{"type":"string","enum":["Inbound","Outbound","Cards"]},"example":"Outbound"},{"name":"currency","in":"query","description":"Filter by currency","required":true,"schema":{"type":"string","example":"USD"}},{"name":"type","in":"query","description":"Filter by document type (e.g., \"LOCAL\", \"GLOBAL\")","required":true,"schema":{"type":"string","enum":["LOCAL","GLOBAL"]},"example":"LOCAL"}],"responses":{"200":{"description":"List of Payment Purpose Codes returned successfully.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListPaymentPurposeCodeResponse"},"example":{"documentTypes":[{"id":1,"category":"Identity Document","title":"Passport","subCategory":"Primary ID","entityType":"individual","provider":null,"paymentDirection":"Inbound","isArchived":false,"createdAt":"2023-01-15T10:30:00Z","updatedAt":"2023-06-20T14:45:00Z"},{"id":2,"category":"Business Document","title":"Certificate of Incorporation","subCategory":"Company Registration","entityType":"business","provider":null,"paymentDirection":"Outbound","isArchived":false}]}}}},"400":{"description":"Bad Request - Invalid paymentDirection value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":400,"message":"Invalid paymentDirection: InvalidValue. Valid values are: Inbound, Outbound, Cards"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/ServerError"}}}}},"components":{"schemas":{"StandardizedPaymentRequest":{"type":"object","description":"Request body for creating a standardized payment request.","discriminator":{"propertyName":"paymentType","mapping":{"WALLET_PAYOUT":"#/components/schemas/StandardizedWalletPayoutRequest","WALLET_TO_BUSINESS":"#/components/schemas/StandardizedWalletToBusinessRequest","TRANSFER_WITHIN_WALLETS":"#/components/schemas/StandardizedTransferWithinWalletsRequest"}},"oneOf":[{"$ref":"#/components/schemas/StandardizedWalletPayoutRequest"},{"$ref":"#/components/schemas/StandardizedWalletToBusinessRequest"},{"$ref":"#/components/schemas/StandardizedTransferWithinWalletsRequest"}]},"StandardizedPaymentResponse":{"type":"object","description":"Response for a standardized payment request.","required":["type","reference","state"],"properties":{"type":{"$ref":"#/components/schemas/StandardizedPaymentType"},"reference":{"type":"string","minLength":1,"maxLength":50,"description":"Unique reference for the payment request."},"state":{"$ref":"#/components/schemas/StandardizedPaymentState"}},"example":{"reference":"TO-29072023-114","type":"WALLET_PAYOUT","state":"REQUESTED"}},"ErrorResponse":{"type":"object","description":"Standard error response format.","required":["code","message"],"properties":{"code":{"type":"integer","description":"Indicates the HTTP status code of the error."},"message":{"type":"string","description":"Indicates the error message."}},"example":{"code":400,"message":"Bad Request"}},"TransferParams":{"type":"object","required":["amount","currency","sourceWalletId","targetWalletId"],"properties":{"amount":{"type":"number","example":1000},"currency":{"type":"string","example":"USD"},"sourceWalletId":{"type":"number","example":1},"targetWalletId":{"type":"number","example":2},"description":{"type":"string","nullable":true,"example":"Internal funds movement"},"externalUniqueRef":{"type":"string","example":"PAY1234567890XYZ1234567890ABC","maximum":40,"description":"A unique identifier for the payment, provided by the external system. This reference is used to ensure the uniqueness of each payment request if passed and is meant for record keeping or prevention of duplicate transactions. The id maintenance and responsibility for its uniqueness in the onus of the external system."}}},"TransferResponse":{"type":"object","properties":{"reference":{"type":"string","example":"TO-11012024-005"},"state":{"type":"string","example":"completed"},"amount":{"type":"number","example":1000},"currency":{"type":"string","example":"USD"},"sourceWalletId":{"type":"number","example":1},"targetWalletId":{"type":"number","example":2},"description":{"type":"string","nullable":true,"example":"Internal funds movement"},"externalUniqueRef":{"type":"string","example":"26c8b828-9ee3-4f2a-b98f-fc317f934897"}}},"PaymentIdResponse":{"type":"object","properties":{"reference":{"type":"string","example":"TO-29072023-114"},"paymentId":{"type":"string","example":"807e02f5-7235-4826-aef5-d93c75216b48"},"amount":{"type":"number","format":"float","example":500},"currency":{"type":"string","example":"USD"},"userRecordId":{"type":"integer","example":2669},"walletId":{"type":"integer","example":12582},"state":{"type":"string","example":"completed"},"type":{"type":"string","example":"credit"},"target":{"type":"string","example":"account"},"targetId":{"type":"integer","example":21688},"purpose":{"type":"string","example":"Purchase of Professional Service(s)"},"description":{"type":"string","nullable":true,"example":null},"pricing":{"$ref":"#/components/schemas/Pricing"},"tracking":{"type":"object","example":{}},"transaction":{"$ref":"#/components/schemas/Transaction"}}},"Error":{"required":["message","code"],"type":"object","properties":{"message":{"description":"The error message indicating what the issue is","type":"string"},"code":{"description":"The error code","maximum":1000,"minimum":1,"type":"integer"}},"example":{"code":400,"message":"wrong input"}},"ListPaymentPurposeCodeResponse":{"type":"object","description":"Response containing a list of Payment Purpose Codes","required":["documentTypes"],"properties":{"documentTypes":{"type":"array","items":{"$ref":"#/components/schemas/PaymentPurposeCode"},"description":"Array of Payment Purpose Codes"}}},"StandardizedWalletPayoutRequest":{"type":"object","description":"Request for wallet payout to a bank account.","required":["paymentType"],"properties":{"customPaymentReference":{"$ref":"#/components/schemas/CustomPaymentReference"},"isSplitPayment":{"type":"boolean","default":false,"description":"Indicates whether this is a split payment."},"paymentType":{"type":"string","enum":["WALLET_PAYOUT"],"description":"Type of payment - wallet payout to bank account."},"purposeId":{"type":"string","description":"Purpose identifier for the payment."},"paymentId":{"$ref":"#/components/schemas/PaymentIdempotencyKey"},"recurFrequency":{"$ref":"#/components/schemas/StandardizedRecurFrequency","nullable":true,"description":"Recurrence frequency for scheduled payments. Required when scheduledDate is provided for recurring payments."},"scheduledDate":{"type":"string","format":"date-time","nullable":true,"description":"Scheduled execution date in ISO 8601 format (UTC)."},"sender":{"$ref":"#/components/schemas/SenderInfoReq","nullable":true,"description":"Sender information for the payment."},"sourceAmount":{"type":"number","format":"float","minimum":0.01,"description":"Amount to transfer from source wallet."},"sourceWalletId":{"type":"string","description":"Source wallet identifier."},"supportingDocS3Key":{"type":"string","nullable":true,"description":"S3 key for supporting document."},"supportingDocS3Keys":{"type":"array","items":{"type":"string"},"nullable":true,"description":"List of S3 keys for supporting documents."},"targetAccountId":{"type":"string","description":"Target bank account identifier."},"usageToken":{"type":"string","nullable":true,"description":"Usage token for fee calculation."},"payoutFeeToken":{"type":"string","nullable":true,"description":"Payout fee token for fee calculation."},"verificationOTP":{"type":"string","nullable":true,"description":"OTP for payment verification."}},"example":{"paymentType":"WALLET_PAYOUT","sourceWalletId":"12345","sourceAmount":1000.5,"targetAccountId":"67890","purposeId":"1","customPaymentReference":"Invoice payment #12345"}},"StandardizedWalletToBusinessRequest":{"type":"object","description":"Request for wallet to business transfer.","required":["paymentType","sourceWalletId","sourceAmount","targetCompanyId","purposeId"],"properties":{"customPaymentReference":{"$ref":"#/components/schemas/CustomPaymentReference"},"paymentType":{"type":"string","enum":["WALLET_TO_BUSINESS"],"description":"Type of payment - wallet to business transfer."},"purposeId":{"type":"string","description":"Purpose identifier for the payment."},"paymentId":{"$ref":"#/components/schemas/PaymentIdempotencyKey"},"recurFrequency":{"$ref":"#/components/schemas/StandardizedRecurFrequency","nullable":true,"description":"Recurrence frequency for scheduled payments. Required when scheduledDate is provided for recurring payments."},"scheduledDate":{"type":"string","format":"date-time","nullable":true,"description":"Scheduled execution date in ISO 8601 format (UTC)."},"sourceAmount":{"type":"number","format":"float","minimum":0.01,"description":"Amount to transfer from source wallet."},"sourceWalletId":{"type":"string","description":"Source wallet identifier."},"supportingDocS3Key":{"type":"string","nullable":true,"description":"S3 key for supporting document."},"supportingDocS3Keys":{"type":"array","items":{"type":"string"},"nullable":true,"description":"List of S3 keys for supporting documents."},"targetCompanyId":{"type":"string","description":"Target company identifier (numeric user-record id as a string). Must be a positive integer string; non-numeric values are rejected by the service.\n"},"verificationOTP":{"type":"string","nullable":true,"description":"OTP for payment verification."}},"example":{"paymentType":"WALLET_TO_BUSINESS","sourceWalletId":"12345","sourceAmount":500,"targetCompanyId":"98765","purposeId":"2"}},"StandardizedTransferWithinWalletsRequest":{"type":"object","description":"Request for transfer within wallets.","required":["paymentType","sourceWalletId","sourceAmount","targetWalletId"],"properties":{"customPaymentReference":{"$ref":"#/components/schemas/CustomPaymentReference"},"paymentType":{"type":"string","enum":["TRANSFER_WITHIN_WALLETS"],"description":"Type of payment - transfer within wallets."},"purposeId":{"type":"string","nullable":true,"description":"Purpose identifier for the payment."},"paymentId":{"$ref":"#/components/schemas/PaymentIdempotencyKey"},"sourceAmount":{"type":"number","format":"float","minimum":0.01,"description":"Amount to transfer from source wallet."},"sourceWalletId":{"type":"string","description":"Source wallet identifier."},"supportingDocS3Key":{"type":"string","nullable":true,"description":"S3 key for supporting document."},"supportingDocS3Keys":{"type":"array","items":{"type":"string"},"nullable":true,"description":"List of S3 keys for supporting documents."},"targetWalletId":{"type":"string","description":"Target wallet identifier."}},"example":{"paymentType":"TRANSFER_WITHIN_WALLETS","sourceWalletId":"12345","sourceAmount":250,"targetWalletId":"67890"}},"StandardizedPaymentType":{"type":"string","description":"Type of payment request (standardized UPPERCASE format).","enum":["WALLET_PAYOUT","WALLET_TO_BUSINESS","TRANSFER_WITHIN_WALLETS","CONVERT_WITHIN_WALLETS","CONVERT_WALLET_PAYOUT"]},"StandardizedPaymentState":{"type":"string","description":"State of a payment request (standardized UPPERCASE format).","enum":["REQUESTED","DISPUTED","COMPLETED","REFUNDED","CANCELLED","ARCHIVED","SCHEDULED"]},"Pricing":{"type":"object","properties":{"overageFee":{"type":"number","format":"float","example":0},"usageId":{"type":"string","nullable":true,"example":null},"subscriptionId":{"type":"string","nullable":true,"example":null}}},"Transaction":{"type":"object","properties":{"sender":{"type":"object","example":{}},"receiver":{"type":"object","example":{}}}},"PaymentPurposeCode":{"type":"object","description":"A Payment Purpose Code definition","required":["id","category","title","isArchived"],"properties":{"id":{"type":"integer","description":"Unique identifier for the document type"},"category":{"type":"string","description":"Category of the document (e.g., \"Identity Document\", \"Payment Purpose\")"},"title":{"type":"string","description":"Display title of the document type"},"subCategory":{"type":"string","nullable":true,"description":"Sub-category of the document type"},"entityType":{"type":"string","nullable":true,"description":"Entity type this document applies to (e.g., \"individual\", \"business\")"},"provider":{"type":"string","nullable":true,"description":"Provider associated with this document type"},"paymentDirection":{"type":"string","nullable":true,"enum":["Inbound","Outbound","Cards"],"description":"Payment direction this document type is associated with"},"isArchived":{"type":"boolean","description":"Whether the document type is archived"},"createdAt":{"type":"string","format":"date-time","description":"Timestamp when the document type was created"},"updatedAt":{"type":"string","format":"date-time","description":"Timestamp when the document type was last updated"}}},"CustomPaymentReference":{"type":"string","nullable":true,"description":"Free-text reference stored against the payment. Not unique and not used for\nduplicate detection; use `paymentId` for idempotency.\n","example":"INV-2024-001"},"PaymentIdempotencyKey":{"type":"string","description":"Optional idempotency key that you generate. This is the field Verto uses to\nreject duplicate payment requests; if you omit it, no duplicate check is\napplied. A UUID is recommended.\n"},"StandardizedRecurFrequency":{"type":"string","description":"Recurrence frequency for scheduled payments (standardized UPPERCASE format).","enum":["ONE_TIME","WEEKLY","MONTHLY"]},"SenderInfoReq":{"type":"object","description":"Sender information for payment transactions","properties":{"type":{"type":"string","description":"Sender type","enum":["individual","company"],"example":"individual"},"originationCountry":{"type":"string","description":"Country of origination","minLength":2,"example":"US"},"customerIdentificationNumber":{"type":"string","description":"Internal customer identification number","minLength":2,"example":"CID123456"},"accountNumber":{"type":"string","description":"Bank account number (optional)","minLength":2,"example":"1234567890","nullable":true},"name":{"type":"string","description":"Sender's full name (individual) or company name (company)","minLength":2,"example":"John Doe"},"nationality":{"type":"string","description":"Country of nationality (mandatory for individual senders)","minLength":2,"example":"US","nullable":true},"registrationCountry":{"type":"string","description":"Registration country (mandatory for company senders)","minLength":2,"example":"US","nullable":true},"dob":{"type":"string","format":"date","description":"Sender's date of birth in DD/MM/YYYY format (mandatory for individual senders)","example":"1990-01-15","nullable":true},"subCategory":{"type":"string","description":"Industry/sub-category (mandatory for company senders)","minLength":2,"example":"technology","nullable":true},"companyRegistrationNumber":{"type":"string","description":"Company registration number (mandatory for company senders)","minLength":2,"example":"REG123456","nullable":true},"addressLine1":{"type":"string","description":"Street, house number, building etc.","minLength":2,"example":"123 Main St"},"addressLine2":{"type":"string","description":"Apartment, suite, unit (optional)","minLength":2,"example":"Apt 4B","nullable":true},"addressCity":{"type":"string","description":"City","minLength":2,"example":"New York"},"zipCode":{"type":"string","description":"ZIP/postal code","minLength":2,"example":"10001"},"country":{"type":"string","description":"Country","minLength":2,"example":"US"},"originationCity":{"type":"string","description":"City of origination (optional)","minLength":2,"example":"New York"}}}},"responses":{"BadRequest":{"description":"Bad Request","content":{"application/json":{"example":{"message":"Bad Request"}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"example":{"message":"Unauthorized"}}}},"ServerError":{"description":"Internal Server Error","content":{"application/json":{"example":{"message":"Internal Server Error"}}}},"Forbidden":{"description":"Forbidden","content":{"application/json":{"example":{"message":"Forbidden"}}}},"NotFound":{"description":"The specified resource was not found","content":{"application/json":{"example":{"message":"Not Found"}}}}}},"security":[],"servers":[{"url":"https://api-payment-sandbox.vertofx.com"},{"url":"https://api-payment-beta.vertofx.com"}]}