# Create Payments

## Create payment

> Payment request, used for DEPOSITS, WITHDRAWALS and REFUNDS

```json
{"openapi":"3.1.1","info":{"title":"convergegate.com API","version":"1.0.76"},"tags":[{"name":"Payments","description":"Payments API"}],"servers":[{"url":"https://engine-sandbox.convergegate.com","description":"Sandbox"},{"url":"https://engine.convergegate.com","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","description":"The client sends HTTP requests with the Authorization header that contains the word Bearer followed by a space and the Shop Api Key.","scheme":"bearer"}},"schemas":{"PaymentRequest":{"required":["currency","paymentType","customer","billingAddress"],"type":"object","properties":{"referenceId":{"maxLength":256,"type":"string","description":"Reference assigned by Merchant. Will not go outside the system. Will be sent unchanged in the PaymentResponse."},"paymentType":{"$ref":"#/components/schemas/PaymentType"},"paymentMethod":{"$ref":"#/components/schemas/PaymentMethod"},"amount":{"multipleOf":1e-18,"maximum":1000000000,"minimum":0.00001,"type":"number","description":"Payment amount"},"currency":{"type":"string","description":"Payment currency","format":"ISO 4217 code for FIAT currencies or cryptocurrency symbol"},"parentPaymentId":{"maxLength":32,"type":"string","description":"Id of initial deposit for refunds, Id of initial recurring payment for subsequent payments"},"description":{"maxLength":512,"type":"string","description":"Description of the transaction shown to the Customer. Can be sent outside the system."},"card":{"$ref":"#/components/schemas/Card"},"customer":{"$ref":"#/components/schemas/Customer"},"billingAddress":{"$ref":"#/components/schemas/BillingAddress"},"returnUrl":{"maxLength":512,"type":"string","description":"URL to redirect Customer after processing"},"webhookUrl":{"maxLength":512,"type":"string","description":"Url to receive payment status notifications"},"startRecurring":{"type":"boolean","description":"Send 'true' if you want this payment to initiate recurring chain. Default is 'false'."},"preAuth":{"type":"boolean","description":"Send 'true' if you want to request a Pre-Authorization charge (initiate a 2-phase deposit)."},"recurringToken":{"type":"string","description":"To continue recurring chain, send a token from a previously initiated recurring payment."},"subscription":{"$ref":"#/components/schemas/SubscriptionRequest"},"additionalParameters":{"type":"object","description":"Additional parameters required by some payment providers. Contact support for more information.","additionalProperties":{"type":"string"}}}},"PaymentType":{"type":"string","description":"Payment Type","enum":["DEPOSIT","WITHDRAWAL","REFUND"]},"PaymentMethod":{"type":"string","description":"Payment Method","enum":["APPLEPAY","BASIC_CARD","BLIK","GOOGLEPAY","OPEN_BANKING","PAY_BY_LINK","PIX"]},"Card":{"type":"object","properties":{"cardNumber":{"maxLength":23,"type":"string","description":"Card primary account number (PAN). All non-numeric characters will be ignored."},"cardToken":{"maxLength":32,"type":"string","description":"Card token which can be used instead of full card number."},"cardholderName":{"maxLength":128,"type":"string","description":"Cardholder's name printed on the card"},"cardSecurityCode":{"minLength":3,"maxLength":4,"type":"string","description":"Card security code (CVV2 / CVC2 / CAV2)"},"expiryMonth":{"minLength":2,"maxLength":2,"type":"string","description":"Card expiration month, 2 digits"},"expiryYear":{"minLength":4,"maxLength":4,"type":"string","description":"Card expiration year, 4 digits"}},"description":"You must be PCI DSS compliant to collect card data on your side. If you are not certified, do not add this field to your request and we will collect the data on our page."},"Customer":{"type":"object","required":["phone","email","firstName","lastName","ip"],"properties":{"referenceId":{"maxLength":128,"type":"string","description":"Id of the customer assigned by Merchant"},"citizenshipCountryCode":{"maxLength":2,"minLength":2,"type":"string","description":"Customer country of citizenship"},"firstName":{"maxLength":128,"type":"string"},"lastName":{"maxLength":128,"type":"string"},"dateOfBirth":{"maxLength":10,"minLength":10,"type":"string","format":"ISO 8601 (YYYY-MM-DD)"},"email":{"maxLength":256,"type":"string","description":"Email address of the customer","format":"email"},"phone":{"maxLength":18,"type":"string","description":"International phone number of the customer, without the '+'. Use a space as a separator between the dialing country code and local phone number."},"locale":{"maxLength":2,"minLength":2,"type":"string","description":"Customer preferred display language"},"accountNumber":{"maxLength":256,"type":"string","description":"Customer account number in the provider's system. Used for some types of withdrawals."},"accountName":{"maxLength":64,"type":"string","description":"Customer account name in the provider's system. Used for some types of withdrawals."},"accountType":{"$ref":"#/components/schemas/AccountType"},"bank":{"maxLength":64,"type":"string","description":"Customer bank name. Used for some types of withdrawals."},"bankCode":{"maxLength":64,"type":"string","description":"Customer bank code. Used for some types of withdrawals."},"bankBranch":{"maxLength":64,"type":"string","description":"Customer bank branch name. Used for some types of withdrawals."},"bankBranchCode":{"maxLength":64,"type":"string","description":"Customer bank branch code. Used for some types of withdrawals."},"documentType":{"$ref":"#/components/schemas/DocumentType"},"documentNumber":{"maxLength":64,"type":"string","description":"An identifier for the customer assigned by a government authority"},"routingGroup":{"maxLength":64,"type":"string","description":"Identify the customer as belonging to a specific group that is used for routing"},"kycStatus":{"type":"boolean","description":"Indicates whether the customer has passed KYC verification"},"paymentInstrumentKycStatus":{"type":"boolean","description":"Indicates whether the payment instrument (usually the card number) has passed KYC verification"},"dateOfFirstDeposit":{"type":"string","format":"ISO 8601 (YYYY-MM-DD)","description":"Date of the first deposit from the customer"},"depositsAmount":{"type":"integer","description":"How much the customer has deposited, in base currency"},"withdrawalsAmount":{"type":"integer","description":"How much the customer has withdrawn, in base currency"},"depositsCnt":{"type":"integer","description":"How many times the customer made a deposit"},"withdrawalsCnt":{"type":"integer","description":"How many times the customer made a withdrawal"},"ip":{"type":"string","description":"The IP address of the customer"}}},"AccountType":{"type":"string","description":"Account Type","enum":["SAVINGS","CHECKING"]},"DocumentType":{"type":"string","description":"Document Type","enum":["AR_CDI","AR_PP","AR_CUIL","AR_CUIT","AR_DNI","AR_OTRO","BO_CEX","BO_CI","BO_NIT","BO_OD","BO_PP","BR_CNPJ","BR_CPF","BR_PP","CL_CE","CL_CI","CL_ID","CL_OTRO","CL_PP","CL_RUN","CL_RUT","CL_TIN","CO_CC","CO_CE","CO_DL","CO_DNI","CO_NE","CO_NIT","CO_PP","CO_SS","CO_TI","CO_TIN","CR_CDI","EC_CC","EC_DNI","EC_PP","EC_RUC","GT_CUI","GT_DPI","GT_NIT","IN_DL","IN_ID","IN_UID","MX_CRI","MX_CURP","MX_IFE","MX_PP","MX_RFC","MX_TIN","PA_CIP","PE_CE","PE_CPP","PE_DNI","PE_FRC","PE_ID","PE_OTRO","PE_PP","PE_RUC","PE_TIN","UY_CI","UY_RUT","VN_TIN"]},"BillingAddress":{"type":"object","required":["countryCode","addressLine1","city","postalCode"],"properties":{"addressLine1":{"maxLength":50,"type":"string","description":"Line 1 of the address (e.g., Number, street, etc)"},"addressLine2":{"maxLength":50,"type":"string","description":"Line 2 of the address (e.g., Suite, apt)"},"city":{"maxLength":50,"type":"string","description":"City name"},"countryCode":{"maxLength":2,"minLength":2,"pattern":"[A-Z]{2}","type":"string","description":"2-character IS0-3166-1 country code"},"postalCode":{"maxLength":12,"type":"string","description":"Postal code"},"state":{"maxLength":40,"type":"string","description":"State code"}},"description":"Customer's billing address"},"SubscriptionRequest":{"required":["frequency"],"type":"object","properties":{"description":{"maxLength":512,"type":"string","description":"Description for subsequent recurring payments"},"amount":{"type":"number","description":"The amount to be used for subsequent payments. If not specified, the amount of the original payment is used."},"startTime":{"type":"string","format":"ISO 8601 (YYYY-MM-DD'T'HH24:MI:SS)","description":"Date and time of the 1st cycle. if not specified, then calculated as (initialDeposit.createTime + frequency*frequencyUnit)."},"frequency":{"type":"integer","minimum":1,"description":"The number of intervals after which a subscriber is billed. For example, if the frequencyUnit is DAY with an frequency of 2, the subscription is billed once every two days."},"frequencyUnit":{"type":"string","description":"The interval at which the subscription is billed. Use 'MINUTE' for testing purposes only.","enum":["MINUTE","DAY","WEEK","MONTH"]},"numberOfCycles":{"type":"integer","minimum":1,"description":"Required number of subsequent recurring payments. Unlimited if value is not specified."},"retryStrategy":{"$ref":"#/components/schemas/SubscriptionRetryStrategy"}},"description":"Subscription to bill customers at regular intervals. Used only with 'startRecurring=true'."},"SubscriptionRetryStrategy":{"required":["frequency","numberOfCycles"],"type":"object","properties":{"frequency":{"type":"integer","minimum":1,"description":"The number of intervals after which the system will retry the payment after an unsuccessful attempt"},"frequencyUnit":{"type":"string","description":"The interval at which the subscription is retried. Use 'MINUTE' for testing purposes only.","enum":["MINUTE","DAY","WEEK","MONTH"]},"numberOfCycles":{"type":"integer","minimum":1,"description":"Required number of retries"},"amountAdjustments":{"type":"array","description":"If specified, the nth element contains the percentage of the initial amount that will be charged for the nth retry","items":{"type":"integer","minimum":1}}},"description":"Retry strategy for subscription. If not specified, the subscription is canceled after the first failed payment attempt."},"PaymentResponse":{"type":"object","properties":{"timestamp":{"type":"string","format":"ISO 8601"},"status":{"type":"integer","description":"HTTP status code"},"result":{"$ref":"#/components/schemas/Payment"}}},"Payment":{"type":"object","properties":{"id":{"maxLength":32,"type":"string","description":"Payment Id"},"referenceId":{"maxLength":256,"type":"string","description":"referenceId from payment request"},"created":{"type":"string","format":"ISO 8601 (YYYY-MM-DD'T'HH24:MI:SS)","description":"Date and time when this payment was created, in UTC time zone"},"paymentType":{"$ref":"#/components/schemas/PaymentType"},"state":{"$ref":"#/components/schemas/PaymentState"},"description":{"maxLength":512,"type":"string","description":"Description of the transaction"},"parentPaymentId":{"maxLength":32,"type":"string","description":"Initial transaction Id from payment request"},"paymentMethod":{"$ref":"#/components/schemas/PaymentMethod"},"paymentMethodDetails":{"$ref":"#/components/schemas/PaymentMethodDetails"},"amount":{"multipleOf":1e-18,"maximum":1000000000,"minimum":0.00001,"type":"number","description":"Amount sent to the payment provider"},"currency":{"type":"string","description":"Currency sent to the payment provider","format":"ISO 4217 code for FIAT currencies or cryptocurrency symbol"},"customerAmount":{"type":"number","description":"Amount from payment request. Filled only if the request currency differs from the currency sent to the payment provider."},"customerCurrency":{"type":"string","description":"Currency from payment request. Filled only if it differs from the currency sent to the payment provider.","format":"ISO 4217 code for FIAT currencies or cryptocurrency symbol"},"redirectUrl":{"maxLength":256,"type":"string","description":"URL to redirect the customer"},"errorCode":{"type":"string","description":"Check 'Error Codes' section for details"},"errorMessage":{"type":"string","description":"Check 'Error Codes' section for details"},"externalResultCode":{"type":"string","description":"Result code from external provider"},"customer":{"$ref":"#/components/schemas/Customer"},"billingAddress":{"$ref":"#/components/schemas/BillingAddress"},"startRecurring":{"type":"boolean","description":"Indicates whether this payment has started a recurring chain"},"preAuth":{"type":"boolean","description":"Indicates whether this is a Pre-Authorization request (for 2-phase deposit)"},"recurringToken":{"type":"string","description":"Token that can be used to continue the recurring chain"},"terminalName":{"type":"string","description":"The name of the provider that was used to process this payment"},"externalFeeAmount":{"type":"number","description":"Provider fee. Filled only if supported by the provider."},"externalFeeCurrency":{"type":"string","description":"Provider fee currency. Filled only if supported by the provider.","format":"ISO 4217 code for FIAT currencies or cryptocurrency symbol"}}},"PaymentState":{"type":"string","description":"Payment State","enum":["CHECKOUT","PENDING","AUTHORIZED","CANCELLED","DECLINED","COMPLETED"]},"PaymentMethodDetails":{"type":"object","properties":{"customerAccountNumber":{"maxLength":256,"type":"string","description":"Customer account Id in external system or masked card PAN"},"cardToken":{"maxLength":32,"type":"string","description":"Card token which can be used instead of full card number (for BASIC_CARD payment method only)"},"cardholderName":{"maxLength":128,"type":"string","description":"Cardholder name (for BASIC_CARD payment method only)"},"cardExpiryMonth":{"minLength":2,"maxLength":2,"type":"string","description":"Card expiration month (for BASIC_CARD payment method only)"},"cardExpiryYear":{"minLength":4,"maxLength":4,"type":"string","description":"Card expiration year (for BASIC_CARD payment method only)"},"cardBrand":{"type":"string","description":"Card brand (for BASIC_CARD payment method only)","enum":["AMEX","DINERS","DISCOVER","JCB","MAESTRO","MASTERCARD","MIR","RUPAY","UNIONPAY","VISA","HUMO","VERVE","TROY","UNKNOWN"]},"cardIssuingCountryCode":{"minLength":2,"maxLength":2,"type":"string","description":"Card issuing country code (for BASIC_CARD payment method only)"}}},"BadRequestError":{"type":"object","properties":{"timestamp":{"type":"string","format":"ISO 8601"},"status":{"type":"integer"},"error":{"type":"string"},"message":{"type":"string"},"errors":{"type":"array","items":{"type":"object","properties":{"codes":{"type":"array","items":{"type":"string"}},"arguments":{"type":"array","items":{"type":"object","properties":{"codes":{"type":"array","items":{"type":"string"}},"defaultMessage":{"type":"string"}}}},"defaultMessage":{"type":"string"},"objectName":{"type":"string"},"field":{"type":"string"},"bindingFailure":{"type":"boolean"}}}},"path":{"type":"string"}}},"UnauthorizedError":{"type":"object","properties":{"status":{"type":"integer"},"error":{"type":"string"},"message":{"type":"string"},"timestamp":{"type":"string","format":"ISO 8601"},"path":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequestError"}}}},"Unauthorized":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UnauthorizedError"}}}}}},"paths":{"/api/v1/payments":{"post":{"tags":["Payments"],"summary":"Create payment","description":"Payment request, used for DEPOSITS, WITHDRAWALS and REFUNDS","operationId":"createPayment","requestBody":{"description":"Payment Request - Request to initiate a payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"}}},"required":true},"responses":{"200":{"description":"Payment response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}
```