{"openapi":"3.1.0","paths":{"/api/v1/payment/card/auth":{"post":{"description":"Creates an authorization hold on a card for a specified amount without capturing the funds.\n\n## Test Cards\n\n### Approved (no 3DS)\n| PAN | statusCode | responseCode |\n|-----|------------|--------------|\n| 4242424242424242 | approved | 0 |\n| 4111111111111111 | approved | 0 |\n| 5555555555554444 | approved | 0 |\n| 378282246310005 | approved | 0 |\n\n### Approved (3DS challenge)\n| PAN | statusCode | responseCode |\n|-----|------------|--------------|\n| 4000000000003220 | approved | 0 |\n| 4000002500003155 | approved | 0 |\n| 5200828282828210 | approved | 0 |\n\n### Declined\n| PAN | statusCode | responseCode |\n|-----|------------|--------------|\n| 4000000000000002 | do_not_honor | 5 |\n| 4000000000009995 | insufficient_funds | 51 |\n| 4000000000000069 | expired_card | 54 |\n| 4000000000000127 | invalid_cvv | 79 |\n| 4000000000000119 | psp_malfunction | 96 |\n| 4100000000000019 | suspected_fraud | 59 |\n| 4000000000000259 | issuer_err | 91 |\n| 4000000000000341 | 3ds_auth_failure | 103 |\n| 4000000000000051 | psp_timeout | 105 |","summary":"Authorize a card","tags":["payments"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"appId":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[a-z0-9-]+$"},"amount":{"type":"object","properties":{"amt":{"type":"number","exclusiveMinimum":0,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"]},"device":{"type":"object","properties":{"ip":{"anyOf":[{"type":"string","format":"ipv4","pattern":"^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$"},{"type":"string","format":"ipv6","pattern":"^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:))$"}]},"userAgent":{"type":"string"},"deviceType":{"type":"string","enum":["desktop","mobile","tablet","unknown"]}},"required":["ip"],"description":"Enduser device details"},"user":{"type":"object","properties":{"userId":{"type":"string","minLength":1,"maxLength":100},"firstName":{"type":"string","minLength":1,"maxLength":100},"middleName":{"type":"string","minLength":1,"maxLength":100},"lastName":{"type":"string","minLength":1,"maxLength":100},"email":{"type":"string","maxLength":500,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$","description":"Email"},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$","description":"Phone number in E.164 format"},"dateOfBirth":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Date of birth in YYYY-MM-DD format"},"address":{"type":"object","properties":{"line1":{"type":"string","maxLength":200},"line2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":100},"state":{"type":"string","maxLength":100},"postalCode":{"type":"string","maxLength":20},"countryCode":{"type":"string","enum":["AFG","ALA","ALB","DZA","ASM","AND","AGO","AIA","ATA","ATG","ARG","ARM","ABW","AUS","AUT","AZE","BHS","BHR","BGD","BRB","BLR","BEL","BLZ","BEN","BMU","BTN","BOL","BES","BIH","BWA","BVT","BRA","IOT","VGB","BRN","BGR","BFA","BDI","KHM","CMR","CAN","CPV","CYM","CAF","TCD","CHL","CHN","CXR","CCK","COL","COM","COG","COD","COK","CRI","CIV","HRV","CUB","CUW","CYP","CZE","DNK","DJI","DMA","DOM","ECU","EGY","SLV","GNQ","ERI","EST","SWZ","ETH","FLK","FRO","FJI","FIN","FRA","GUF","PYF","ATF","GAB","GMB","GEO","DEU","GHA","GIB","GRC","GRL","GRD","GLP","GUM","GTM","GGY","GIN","GNB","GUY","HTI","HMD","HND","HKG","HUN","ISL","IND","IDN","IRN","IRQ","IRL","IMN","ISR","ITA","JAM","JPN","JEY","JOR","KAZ","KEN","KIR","PRK","KOR","KWT","KGZ","LAO","LVA","LBN","LSO","LBR","LBY","LIE","LTU","LUX","MAC","MKD","MDG","MWI","MYS","MDV","MLI","MLT","MHL","MTQ","MRT","MUS","MYT","MEX","FSM","MDA","MCO","MNG","MNE","MSR","MAR","MOZ","MMR","NAM","NRU","NPL","NLD","NCL","NZL","NIC","NER","NGA","NIU","NFK","MNP","NOR","OMN","PAK","PLW","PSE","PAN","PNG","PRY","PER","PHL","PCN","POL","PRT","PRI","QAT","REU","ROU","RUS","RWA","BLM","SHN","KNA","LCA","MAF","SPM","VCT","WSM","SMR","STP","SAU","SEN","SRB","SYC","SLE","SGP","SXM","SVK","SVN","SLB","SOM","ZAF","SGS","SSD","ESP","LKA","SDN","SUR","SJM","SWE","CHE","SYR","TWN","TJK","TZA","THA","TLS","TGO","TKL","TON","TTO","TUN","TUR","TKM","TCA","TUV","UGA","UKR","ARE","GBR","USA","UMI","VIR","URY","UZB","VUT","VAT","VEN","VNM","WLF","ESH","YEM","ZMB","ZWE","ZZZ"]}},"required":["line1","city","postalCode","countryCode"],"description":"Address"},"shippingAddress":{"type":"object","properties":{"line1":{"type":"string","maxLength":200},"line2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":100},"state":{"type":"string","maxLength":100},"postalCode":{"type":"string","maxLength":20},"countryCode":{"type":"string","enum":["AFG","ALA","ALB","DZA","ASM","AND","AGO","AIA","ATA","ATG","ARG","ARM","ABW","AUS","AUT","AZE","BHS","BHR","BGD","BRB","BLR","BEL","BLZ","BEN","BMU","BTN","BOL","BES","BIH","BWA","BVT","BRA","IOT","VGB","BRN","BGR","BFA","BDI","KHM","CMR","CAN","CPV","CYM","CAF","TCD","CHL","CHN","CXR","CCK","COL","COM","COG","COD","COK","CRI","CIV","HRV","CUB","CUW","CYP","CZE","DNK","DJI","DMA","DOM","ECU","EGY","SLV","GNQ","ERI","EST","SWZ","ETH","FLK","FRO","FJI","FIN","FRA","GUF","PYF","ATF","GAB","GMB","GEO","DEU","GHA","GIB","GRC","GRL","GRD","GLP","GUM","GTM","GGY","GIN","GNB","GUY","HTI","HMD","HND","HKG","HUN","ISL","IND","IDN","IRN","IRQ","IRL","IMN","ISR","ITA","JAM","JPN","JEY","JOR","KAZ","KEN","KIR","PRK","KOR","KWT","KGZ","LAO","LVA","LBN","LSO","LBR","LBY","LIE","LTU","LUX","MAC","MKD","MDG","MWI","MYS","MDV","MLI","MLT","MHL","MTQ","MRT","MUS","MYT","MEX","FSM","MDA","MCO","MNG","MNE","MSR","MAR","MOZ","MMR","NAM","NRU","NPL","NLD","NCL","NZL","NIC","NER","NGA","NIU","NFK","MNP","NOR","OMN","PAK","PLW","PSE","PAN","PNG","PRY","PER","PHL","PCN","POL","PRT","PRI","QAT","REU","ROU","RUS","RWA","BLM","SHN","KNA","LCA","MAF","SPM","VCT","WSM","SMR","STP","SAU","SEN","SRB","SYC","SLE","SGP","SXM","SVK","SVN","SLB","SOM","ZAF","SGS","SSD","ESP","LKA","SDN","SUR","SJM","SWE","CHE","SYR","TWN","TJK","TZA","THA","TLS","TGO","TKL","TON","TTO","TUN","TUR","TKM","TCA","TUV","UGA","UKR","ARE","GBR","USA","UMI","VIR","URY","UZB","VUT","VAT","VEN","VNM","WLF","ESH","YEM","ZMB","ZWE","ZZZ"]}},"required":["line1","city","postalCode","countryCode"],"description":"Address"}},"required":["firstName","lastName"],"description":"User details for the payment"},"txRefId":{"type":"string","maxLength":255,"description":"External transaction reference ID"},"successUrl":{"type":"string","format":"uri"},"failureUrl":{"type":"string","format":"uri"},"callbackUrl":{"type":"string","format":"uri"},"card":{"type":"object","properties":{"cardNumber":{"type":"string","description":"Credit or debit card number"},"expiryMonth":{"type":"integer","minimum":1,"maximum":12,"description":"Card expiry month (1-12)"},"expiryYear":{"type":"integer","minimum":1970,"maximum":2100,"description":"Card expiry year (4 digits)"},"cvv":{"type":"string","description":"Card verification value (CVV/CVC)"},"cardHolderName":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-zÀ-ÖØ-öø-ÿ'\\- ]+$","description":"Name of the cardholder as it appears on the card"},"cardBrand":{"type":"string","enum":["VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","ELO","MIR","HIPERCARD","HIPER","DANKORT","RUPAY","ELECTRON","UNKNOWN"]},"iin":{"anyOf":[{"type":"string","minLength":6,"maxLength":6},{"type":"string","minLength":8,"maxLength":8}]},"save":{"type":"boolean"}},"required":["cardNumber","expiryMonth","expiryYear","cvv"],"description":"Credit or debit card details"}},"required":["appId","amount","device","txRefId","card"],"description":"Request schema for debiting a card. Note: when routing to the PSP simulator (non-production environments only), card outcomes are driven by the card PAN and/or amount last-2-digits as documented below."}}}},"responses":{"200":{"description":"API response schema for payment","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"txAmount":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"additionalProperties":false,"description":"Monetary amount with currency"},"txFee":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"additionalProperties":false,"description":"Monetary amount with currency"},"txRefId":{"type":"string","maxLength":255},"state":{"type":"string","enum":["success","processing","waiting","approval","declined","unknown","error","cancelled"],"description":"Payment transaction state"},"statusCode":{"type":"string","enum":["approved","manually_approved","do_not_honor","suspected_fraud","invalid_trx","invalid_amt","invalid_account","invalid_response","no_transaction","restricted_card","insufficient_funds","expired_card","trx_not_permitted","exceeds_limit","exceeds_frequency","invalid_cvv","issuer_err","dest_not_found","psp_malfunction","unable_to_authorize","3ds_auth_failure","psp_limits_reached","psp_timeout","user_aborted_trx","avs_response","no_auth_corresponding","already_captured","already_cancelled","already_refunded","unknown_card","currency_not_supported","amt_over_max","amt_under_min","mobile_block","email_block","ip_block","bin_block","device_block","user_block","account_block","risk_block","duplicate_trx","already_chargedback","too_old_to_refund","no_partial_refund","partial_refund_over","redirect","redirect_timeout","processing","routing_error","system_error","psp_error","bad_request","other"],"description":"Harmonized response codes"},"extStatusCode":{"type":"string"},"statusMessage":{"type":"string"},"redirectUrl":{"type":"string","format":"uri"}},"required":["id"],"additionalProperties":false,"description":"API response schema for payment"}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}}}},"/api/v1/payment/card/debit":{"post":{"description":"Creates an authorization hold on a card for a specified amount without capturing the funds.\n\n## Test Cards\n\n### Approved (no 3DS)\n| PAN | statusCode | responseCode |\n|-----|------------|--------------|\n| 4242424242424242 | approved | 0 |\n| 4111111111111111 | approved | 0 |\n| 5555555555554444 | approved | 0 |\n| 378282246310005 | approved | 0 |\n\n### Approved (3DS challenge)\n| PAN | statusCode | responseCode |\n|-----|------------|--------------|\n| 4000000000003220 | approved | 0 |\n| 4000002500003155 | approved | 0 |\n| 5200828282828210 | approved | 0 |\n\n### Declined\n| PAN | statusCode | responseCode |\n|-----|------------|--------------|\n| 4000000000000002 | do_not_honor | 5 |\n| 4000000000009995 | insufficient_funds | 51 |\n| 4000000000000069 | expired_card | 54 |\n| 4000000000000127 | invalid_cvv | 79 |\n| 4000000000000119 | psp_malfunction | 96 |\n| 4100000000000019 | suspected_fraud | 59 |\n| 4000000000000259 | issuer_err | 91 |\n| 4000000000000341 | 3ds_auth_failure | 103 |\n| 4000000000000051 | psp_timeout | 105 |","summary":"Debit a card","tags":["payments"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"appId":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[a-z0-9-]+$"},"amount":{"type":"object","properties":{"amt":{"type":"number","exclusiveMinimum":0,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"]},"device":{"type":"object","properties":{"ip":{"anyOf":[{"type":"string","format":"ipv4","pattern":"^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$"},{"type":"string","format":"ipv6","pattern":"^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:))$"}]},"userAgent":{"type":"string"},"deviceType":{"type":"string","enum":["desktop","mobile","tablet","unknown"]}},"required":["ip"],"description":"Enduser device details"},"user":{"type":"object","properties":{"userId":{"type":"string","minLength":1,"maxLength":100},"firstName":{"type":"string","minLength":1,"maxLength":100},"middleName":{"type":"string","minLength":1,"maxLength":100},"lastName":{"type":"string","minLength":1,"maxLength":100},"email":{"type":"string","maxLength":500,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$","description":"Email"},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$","description":"Phone number in E.164 format"},"dateOfBirth":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Date of birth in YYYY-MM-DD format"},"address":{"type":"object","properties":{"line1":{"type":"string","maxLength":200},"line2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":100},"state":{"type":"string","maxLength":100},"postalCode":{"type":"string","maxLength":20},"countryCode":{"type":"string","enum":["AFG","ALA","ALB","DZA","ASM","AND","AGO","AIA","ATA","ATG","ARG","ARM","ABW","AUS","AUT","AZE","BHS","BHR","BGD","BRB","BLR","BEL","BLZ","BEN","BMU","BTN","BOL","BES","BIH","BWA","BVT","BRA","IOT","VGB","BRN","BGR","BFA","BDI","KHM","CMR","CAN","CPV","CYM","CAF","TCD","CHL","CHN","CXR","CCK","COL","COM","COG","COD","COK","CRI","CIV","HRV","CUB","CUW","CYP","CZE","DNK","DJI","DMA","DOM","ECU","EGY","SLV","GNQ","ERI","EST","SWZ","ETH","FLK","FRO","FJI","FIN","FRA","GUF","PYF","ATF","GAB","GMB","GEO","DEU","GHA","GIB","GRC","GRL","GRD","GLP","GUM","GTM","GGY","GIN","GNB","GUY","HTI","HMD","HND","HKG","HUN","ISL","IND","IDN","IRN","IRQ","IRL","IMN","ISR","ITA","JAM","JPN","JEY","JOR","KAZ","KEN","KIR","PRK","KOR","KWT","KGZ","LAO","LVA","LBN","LSO","LBR","LBY","LIE","LTU","LUX","MAC","MKD","MDG","MWI","MYS","MDV","MLI","MLT","MHL","MTQ","MRT","MUS","MYT","MEX","FSM","MDA","MCO","MNG","MNE","MSR","MAR","MOZ","MMR","NAM","NRU","NPL","NLD","NCL","NZL","NIC","NER","NGA","NIU","NFK","MNP","NOR","OMN","PAK","PLW","PSE","PAN","PNG","PRY","PER","PHL","PCN","POL","PRT","PRI","QAT","REU","ROU","RUS","RWA","BLM","SHN","KNA","LCA","MAF","SPM","VCT","WSM","SMR","STP","SAU","SEN","SRB","SYC","SLE","SGP","SXM","SVK","SVN","SLB","SOM","ZAF","SGS","SSD","ESP","LKA","SDN","SUR","SJM","SWE","CHE","SYR","TWN","TJK","TZA","THA","TLS","TGO","TKL","TON","TTO","TUN","TUR","TKM","TCA","TUV","UGA","UKR","ARE","GBR","USA","UMI","VIR","URY","UZB","VUT","VAT","VEN","VNM","WLF","ESH","YEM","ZMB","ZWE","ZZZ"]}},"required":["line1","city","postalCode","countryCode"],"description":"Address"},"shippingAddress":{"type":"object","properties":{"line1":{"type":"string","maxLength":200},"line2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":100},"state":{"type":"string","maxLength":100},"postalCode":{"type":"string","maxLength":20},"countryCode":{"type":"string","enum":["AFG","ALA","ALB","DZA","ASM","AND","AGO","AIA","ATA","ATG","ARG","ARM","ABW","AUS","AUT","AZE","BHS","BHR","BGD","BRB","BLR","BEL","BLZ","BEN","BMU","BTN","BOL","BES","BIH","BWA","BVT","BRA","IOT","VGB","BRN","BGR","BFA","BDI","KHM","CMR","CAN","CPV","CYM","CAF","TCD","CHL","CHN","CXR","CCK","COL","COM","COG","COD","COK","CRI","CIV","HRV","CUB","CUW","CYP","CZE","DNK","DJI","DMA","DOM","ECU","EGY","SLV","GNQ","ERI","EST","SWZ","ETH","FLK","FRO","FJI","FIN","FRA","GUF","PYF","ATF","GAB","GMB","GEO","DEU","GHA","GIB","GRC","GRL","GRD","GLP","GUM","GTM","GGY","GIN","GNB","GUY","HTI","HMD","HND","HKG","HUN","ISL","IND","IDN","IRN","IRQ","IRL","IMN","ISR","ITA","JAM","JPN","JEY","JOR","KAZ","KEN","KIR","PRK","KOR","KWT","KGZ","LAO","LVA","LBN","LSO","LBR","LBY","LIE","LTU","LUX","MAC","MKD","MDG","MWI","MYS","MDV","MLI","MLT","MHL","MTQ","MRT","MUS","MYT","MEX","FSM","MDA","MCO","MNG","MNE","MSR","MAR","MOZ","MMR","NAM","NRU","NPL","NLD","NCL","NZL","NIC","NER","NGA","NIU","NFK","MNP","NOR","OMN","PAK","PLW","PSE","PAN","PNG","PRY","PER","PHL","PCN","POL","PRT","PRI","QAT","REU","ROU","RUS","RWA","BLM","SHN","KNA","LCA","MAF","SPM","VCT","WSM","SMR","STP","SAU","SEN","SRB","SYC","SLE","SGP","SXM","SVK","SVN","SLB","SOM","ZAF","SGS","SSD","ESP","LKA","SDN","SUR","SJM","SWE","CHE","SYR","TWN","TJK","TZA","THA","TLS","TGO","TKL","TON","TTO","TUN","TUR","TKM","TCA","TUV","UGA","UKR","ARE","GBR","USA","UMI","VIR","URY","UZB","VUT","VAT","VEN","VNM","WLF","ESH","YEM","ZMB","ZWE","ZZZ"]}},"required":["line1","city","postalCode","countryCode"],"description":"Address"}},"required":["firstName","lastName"],"description":"User details for the payment"},"txRefId":{"type":"string","maxLength":255,"description":"External transaction reference ID"},"successUrl":{"type":"string","format":"uri"},"failureUrl":{"type":"string","format":"uri"},"callbackUrl":{"type":"string","format":"uri"},"card":{"type":"object","properties":{"cardNumber":{"type":"string","description":"Credit or debit card number"},"expiryMonth":{"type":"integer","minimum":1,"maximum":12,"description":"Card expiry month (1-12)"},"expiryYear":{"type":"integer","minimum":1970,"maximum":2100,"description":"Card expiry year (4 digits)"},"cvv":{"type":"string","description":"Card verification value (CVV/CVC)"},"cardHolderName":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-zÀ-ÖØ-öø-ÿ'\\- ]+$","description":"Name of the cardholder as it appears on the card"},"cardBrand":{"type":"string","enum":["VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","ELO","MIR","HIPERCARD","HIPER","DANKORT","RUPAY","ELECTRON","UNKNOWN"]},"iin":{"anyOf":[{"type":"string","minLength":6,"maxLength":6},{"type":"string","minLength":8,"maxLength":8}]},"save":{"type":"boolean"}},"required":["cardNumber","expiryMonth","expiryYear","cvv"],"description":"Credit or debit card details"}},"required":["appId","amount","device","txRefId","card"],"description":"Request schema for debiting a card. Note: when routing to the PSP simulator (non-production environments only), card outcomes are driven by the card PAN and/or amount last-2-digits as documented below."}}}},"responses":{"200":{"description":"API response schema for payment","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"txAmount":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"additionalProperties":false,"description":"Monetary amount with currency"},"txFee":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"additionalProperties":false,"description":"Monetary amount with currency"},"txRefId":{"type":"string","maxLength":255},"state":{"type":"string","enum":["success","processing","waiting","approval","declined","unknown","error","cancelled"],"description":"Payment transaction state"},"statusCode":{"type":"string","enum":["approved","manually_approved","do_not_honor","suspected_fraud","invalid_trx","invalid_amt","invalid_account","invalid_response","no_transaction","restricted_card","insufficient_funds","expired_card","trx_not_permitted","exceeds_limit","exceeds_frequency","invalid_cvv","issuer_err","dest_not_found","psp_malfunction","unable_to_authorize","3ds_auth_failure","psp_limits_reached","psp_timeout","user_aborted_trx","avs_response","no_auth_corresponding","already_captured","already_cancelled","already_refunded","unknown_card","currency_not_supported","amt_over_max","amt_under_min","mobile_block","email_block","ip_block","bin_block","device_block","user_block","account_block","risk_block","duplicate_trx","already_chargedback","too_old_to_refund","no_partial_refund","partial_refund_over","redirect","redirect_timeout","processing","routing_error","system_error","psp_error","bad_request","other"],"description":"Harmonized response codes"},"extStatusCode":{"type":"string"},"statusMessage":{"type":"string"},"redirectUrl":{"type":"string","format":"uri"}},"required":["id"],"additionalProperties":false,"description":"API response schema for payment"}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}}}},"/api/v1/payment/card/credit":{"post":{"description":"Push funds directly to a card (Original Credit Transaction / payout). Card details are supplied by the caller — no prior transaction reference is required. 3DS authentication does not apply to outbound credit flows.\n\n## Test Cards\n\n### Approved\n| PAN | statusCode | responseCode |\n|-----|------------|--------------|\n| 4242424242424242 | approved | 0 |\n| 4111111111111111 | approved | 0 |\n| 5555555555554444 | approved | 0 |\n| 378282246310005 | approved | 0 |\n\n### Declined\n| PAN | statusCode | responseCode |\n|-----|------------|--------------|\n| 4000000000000002 | do_not_honor | 5 |\n| 4000000000009995 | insufficient_funds | 51 |\n| 4000000000000069 | expired_card | 54 |\n| 4000000000000127 | invalid_cvv | 79 |\n| 4000000000000119 | psp_malfunction | 96 |\n| 4100000000000019 | suspected_fraud | 59 |\n| 4000000000000259 | issuer_err | 91 |\n| 4000000000000051 | psp_timeout | 105 |","summary":"Credit a card (OCT / payout)","tags":["payments"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"appId":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[a-z0-9-]+$"},"amount":{"type":"object","properties":{"amt":{"type":"number","exclusiveMinimum":0,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"]},"device":{"type":"object","properties":{"ip":{"anyOf":[{"type":"string","format":"ipv4","pattern":"^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$"},{"type":"string","format":"ipv6","pattern":"^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:))$"}]},"userAgent":{"type":"string"},"deviceType":{"type":"string","enum":["desktop","mobile","tablet","unknown"]}},"required":["ip"],"description":"Enduser device details"},"user":{"type":"object","properties":{"userId":{"type":"string","minLength":1,"maxLength":100},"firstName":{"type":"string","minLength":1,"maxLength":100},"middleName":{"type":"string","minLength":1,"maxLength":100},"lastName":{"type":"string","minLength":1,"maxLength":100},"email":{"type":"string","maxLength":500,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$","description":"Email"},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$","description":"Phone number in E.164 format"},"dateOfBirth":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Date of birth in YYYY-MM-DD format"},"address":{"type":"object","properties":{"line1":{"type":"string","maxLength":200},"line2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":100},"state":{"type":"string","maxLength":100},"postalCode":{"type":"string","maxLength":20},"countryCode":{"type":"string","enum":["AFG","ALA","ALB","DZA","ASM","AND","AGO","AIA","ATA","ATG","ARG","ARM","ABW","AUS","AUT","AZE","BHS","BHR","BGD","BRB","BLR","BEL","BLZ","BEN","BMU","BTN","BOL","BES","BIH","BWA","BVT","BRA","IOT","VGB","BRN","BGR","BFA","BDI","KHM","CMR","CAN","CPV","CYM","CAF","TCD","CHL","CHN","CXR","CCK","COL","COM","COG","COD","COK","CRI","CIV","HRV","CUB","CUW","CYP","CZE","DNK","DJI","DMA","DOM","ECU","EGY","SLV","GNQ","ERI","EST","SWZ","ETH","FLK","FRO","FJI","FIN","FRA","GUF","PYF","ATF","GAB","GMB","GEO","DEU","GHA","GIB","GRC","GRL","GRD","GLP","GUM","GTM","GGY","GIN","GNB","GUY","HTI","HMD","HND","HKG","HUN","ISL","IND","IDN","IRN","IRQ","IRL","IMN","ISR","ITA","JAM","JPN","JEY","JOR","KAZ","KEN","KIR","PRK","KOR","KWT","KGZ","LAO","LVA","LBN","LSO","LBR","LBY","LIE","LTU","LUX","MAC","MKD","MDG","MWI","MYS","MDV","MLI","MLT","MHL","MTQ","MRT","MUS","MYT","MEX","FSM","MDA","MCO","MNG","MNE","MSR","MAR","MOZ","MMR","NAM","NRU","NPL","NLD","NCL","NZL","NIC","NER","NGA","NIU","NFK","MNP","NOR","OMN","PAK","PLW","PSE","PAN","PNG","PRY","PER","PHL","PCN","POL","PRT","PRI","QAT","REU","ROU","RUS","RWA","BLM","SHN","KNA","LCA","MAF","SPM","VCT","WSM","SMR","STP","SAU","SEN","SRB","SYC","SLE","SGP","SXM","SVK","SVN","SLB","SOM","ZAF","SGS","SSD","ESP","LKA","SDN","SUR","SJM","SWE","CHE","SYR","TWN","TJK","TZA","THA","TLS","TGO","TKL","TON","TTO","TUN","TUR","TKM","TCA","TUV","UGA","UKR","ARE","GBR","USA","UMI","VIR","URY","UZB","VUT","VAT","VEN","VNM","WLF","ESH","YEM","ZMB","ZWE","ZZZ"]}},"required":["line1","city","postalCode","countryCode"],"description":"Address"},"shippingAddress":{"type":"object","properties":{"line1":{"type":"string","maxLength":200},"line2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":100},"state":{"type":"string","maxLength":100},"postalCode":{"type":"string","maxLength":20},"countryCode":{"type":"string","enum":["AFG","ALA","ALB","DZA","ASM","AND","AGO","AIA","ATA","ATG","ARG","ARM","ABW","AUS","AUT","AZE","BHS","BHR","BGD","BRB","BLR","BEL","BLZ","BEN","BMU","BTN","BOL","BES","BIH","BWA","BVT","BRA","IOT","VGB","BRN","BGR","BFA","BDI","KHM","CMR","CAN","CPV","CYM","CAF","TCD","CHL","CHN","CXR","CCK","COL","COM","COG","COD","COK","CRI","CIV","HRV","CUB","CUW","CYP","CZE","DNK","DJI","DMA","DOM","ECU","EGY","SLV","GNQ","ERI","EST","SWZ","ETH","FLK","FRO","FJI","FIN","FRA","GUF","PYF","ATF","GAB","GMB","GEO","DEU","GHA","GIB","GRC","GRL","GRD","GLP","GUM","GTM","GGY","GIN","GNB","GUY","HTI","HMD","HND","HKG","HUN","ISL","IND","IDN","IRN","IRQ","IRL","IMN","ISR","ITA","JAM","JPN","JEY","JOR","KAZ","KEN","KIR","PRK","KOR","KWT","KGZ","LAO","LVA","LBN","LSO","LBR","LBY","LIE","LTU","LUX","MAC","MKD","MDG","MWI","MYS","MDV","MLI","MLT","MHL","MTQ","MRT","MUS","MYT","MEX","FSM","MDA","MCO","MNG","MNE","MSR","MAR","MOZ","MMR","NAM","NRU","NPL","NLD","NCL","NZL","NIC","NER","NGA","NIU","NFK","MNP","NOR","OMN","PAK","PLW","PSE","PAN","PNG","PRY","PER","PHL","PCN","POL","PRT","PRI","QAT","REU","ROU","RUS","RWA","BLM","SHN","KNA","LCA","MAF","SPM","VCT","WSM","SMR","STP","SAU","SEN","SRB","SYC","SLE","SGP","SXM","SVK","SVN","SLB","SOM","ZAF","SGS","SSD","ESP","LKA","SDN","SUR","SJM","SWE","CHE","SYR","TWN","TJK","TZA","THA","TLS","TGO","TKL","TON","TTO","TUN","TUR","TKM","TCA","TUV","UGA","UKR","ARE","GBR","USA","UMI","VIR","URY","UZB","VUT","VAT","VEN","VNM","WLF","ESH","YEM","ZMB","ZWE","ZZZ"]}},"required":["line1","city","postalCode","countryCode"],"description":"Address"}},"required":["firstName","lastName"],"description":"User details for the payment"},"txRefId":{"type":"string","maxLength":255,"description":"External transaction reference ID"},"successUrl":{"type":"string","format":"uri"},"failureUrl":{"type":"string","format":"uri"},"callbackUrl":{"type":"string","format":"uri"},"card":{"type":"object","properties":{"cardNumber":{"type":"string","description":"Credit or debit card number"},"expiryMonth":{"type":"integer","minimum":1,"maximum":12,"description":"Card expiry month (1-12)"},"expiryYear":{"type":"integer","minimum":1970,"maximum":2100,"description":"Card expiry year (4 digits)"},"cvv":{"type":"string","description":"Card verification value (CVV/CVC)"},"cardHolderName":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-zÀ-ÖØ-öø-ÿ'\\- ]+$","description":"Name of the cardholder as it appears on the card"},"cardBrand":{"type":"string","enum":["VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","ELO","MIR","HIPERCARD","HIPER","DANKORT","RUPAY","ELECTRON","UNKNOWN"]},"iin":{"anyOf":[{"type":"string","minLength":6,"maxLength":6},{"type":"string","minLength":8,"maxLength":8}]},"save":{"type":"boolean"}},"required":["cardNumber","expiryMonth","expiryYear"]}},"required":["appId","amount","device","txRefId","card"],"description":"Request schema for crediting (paying out to) a card. No 3DS is required for OCT/payout flows."}}}},"responses":{"200":{"description":"API response schema for payment","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"txAmount":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"additionalProperties":false,"description":"Monetary amount with currency"},"txFee":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"additionalProperties":false,"description":"Monetary amount with currency"},"txRefId":{"type":"string","maxLength":255},"state":{"type":"string","enum":["success","processing","waiting","approval","declined","unknown","error","cancelled"],"description":"Payment transaction state"},"statusCode":{"type":"string","enum":["approved","manually_approved","do_not_honor","suspected_fraud","invalid_trx","invalid_amt","invalid_account","invalid_response","no_transaction","restricted_card","insufficient_funds","expired_card","trx_not_permitted","exceeds_limit","exceeds_frequency","invalid_cvv","issuer_err","dest_not_found","psp_malfunction","unable_to_authorize","3ds_auth_failure","psp_limits_reached","psp_timeout","user_aborted_trx","avs_response","no_auth_corresponding","already_captured","already_cancelled","already_refunded","unknown_card","currency_not_supported","amt_over_max","amt_under_min","mobile_block","email_block","ip_block","bin_block","device_block","user_block","account_block","risk_block","duplicate_trx","already_chargedback","too_old_to_refund","no_partial_refund","partial_refund_over","redirect","redirect_timeout","processing","routing_error","system_error","psp_error","bad_request","other"],"description":"Harmonized response codes"},"extStatusCode":{"type":"string"},"statusMessage":{"type":"string"},"redirectUrl":{"type":"string","format":"uri"}},"required":["id"],"additionalProperties":false,"description":"API response schema for payment"}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}}}},"/api/v1/payment/card/refund":{"post":{"description":"Refunds a previously captured charge.","summary":"Refund a charge","tags":["payments"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"callbackUrl":{"description":"URL to receive webhook callback with transaction result","type":"string","format":"uri"},"manualOverride":{"description":"Operator-only. When true, the provider is not called and the transaction is forced to a successful, manually-approved outcome. Honored only for authenticated operator (user) requests.","type":"boolean"}},"required":["id"]}}}},"responses":{"200":{"description":"API response schema for payment","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"txAmount":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"additionalProperties":false,"description":"Monetary amount with currency"},"txFee":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"additionalProperties":false,"description":"Monetary amount with currency"},"txRefId":{"type":"string","maxLength":255},"state":{"type":"string","enum":["success","processing","waiting","approval","declined","unknown","error","cancelled"],"description":"Payment transaction state"},"statusCode":{"type":"string","enum":["approved","manually_approved","do_not_honor","suspected_fraud","invalid_trx","invalid_amt","invalid_account","invalid_response","no_transaction","restricted_card","insufficient_funds","expired_card","trx_not_permitted","exceeds_limit","exceeds_frequency","invalid_cvv","issuer_err","dest_not_found","psp_malfunction","unable_to_authorize","3ds_auth_failure","psp_limits_reached","psp_timeout","user_aborted_trx","avs_response","no_auth_corresponding","already_captured","already_cancelled","already_refunded","unknown_card","currency_not_supported","amt_over_max","amt_under_min","mobile_block","email_block","ip_block","bin_block","device_block","user_block","account_block","risk_block","duplicate_trx","already_chargedback","too_old_to_refund","no_partial_refund","partial_refund_over","redirect","redirect_timeout","processing","routing_error","system_error","psp_error","bad_request","other"],"description":"Harmonized response codes"},"extStatusCode":{"type":"string"},"statusMessage":{"type":"string"},"redirectUrl":{"type":"string","format":"uri"}},"required":["id"],"additionalProperties":false,"description":"API response schema for payment"}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}}}},"/api/v1/payment/card/void":{"post":{"description":"Cancels an authorization hold without capturing.","summary":"Void an authorization","tags":["payments"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"callbackUrl":{"description":"URL to receive webhook callback with transaction result","type":"string","format":"uri"},"manualOverride":{"description":"Operator-only. When true, the provider is not called and the transaction is forced to a successful, manually-approved outcome. Honored only for authenticated operator (user) requests.","type":"boolean"}},"required":["id"]}}}},"responses":{"200":{"description":"API response schema for payment","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"txAmount":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"additionalProperties":false,"description":"Monetary amount with currency"},"txFee":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"additionalProperties":false,"description":"Monetary amount with currency"},"txRefId":{"type":"string","maxLength":255},"state":{"type":"string","enum":["success","processing","waiting","approval","declined","unknown","error","cancelled"],"description":"Payment transaction state"},"statusCode":{"type":"string","enum":["approved","manually_approved","do_not_honor","suspected_fraud","invalid_trx","invalid_amt","invalid_account","invalid_response","no_transaction","restricted_card","insufficient_funds","expired_card","trx_not_permitted","exceeds_limit","exceeds_frequency","invalid_cvv","issuer_err","dest_not_found","psp_malfunction","unable_to_authorize","3ds_auth_failure","psp_limits_reached","psp_timeout","user_aborted_trx","avs_response","no_auth_corresponding","already_captured","already_cancelled","already_refunded","unknown_card","currency_not_supported","amt_over_max","amt_under_min","mobile_block","email_block","ip_block","bin_block","device_block","user_block","account_block","risk_block","duplicate_trx","already_chargedback","too_old_to_refund","no_partial_refund","partial_refund_over","redirect","redirect_timeout","processing","routing_error","system_error","psp_error","bad_request","other"],"description":"Harmonized response codes"},"extStatusCode":{"type":"string"},"statusMessage":{"type":"string"},"redirectUrl":{"type":"string","format":"uri"}},"required":["id"],"additionalProperties":false,"description":"API response schema for payment"}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}}}},"/api/v1/payment/card/capture":{"post":{"description":"Captures funds from a previously authorized charge.","summary":"Capture an authorization","tags":["payments"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"callbackUrl":{"description":"URL to receive webhook callback with transaction result","type":"string","format":"uri"},"manualOverride":{"description":"Operator-only. When true, the provider is not called and the transaction is forced to a successful, manually-approved outcome. Honored only for authenticated operator (user) requests.","type":"boolean"}},"required":["id"]}}}},"responses":{"200":{"description":"API response schema for payment","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"txAmount":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"additionalProperties":false,"description":"Monetary amount with currency"},"txFee":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"additionalProperties":false,"description":"Monetary amount with currency"},"txRefId":{"type":"string","maxLength":255},"state":{"type":"string","enum":["success","processing","waiting","approval","declined","unknown","error","cancelled"],"description":"Payment transaction state"},"statusCode":{"type":"string","enum":["approved","manually_approved","do_not_honor","suspected_fraud","invalid_trx","invalid_amt","invalid_account","invalid_response","no_transaction","restricted_card","insufficient_funds","expired_card","trx_not_permitted","exceeds_limit","exceeds_frequency","invalid_cvv","issuer_err","dest_not_found","psp_malfunction","unable_to_authorize","3ds_auth_failure","psp_limits_reached","psp_timeout","user_aborted_trx","avs_response","no_auth_corresponding","already_captured","already_cancelled","already_refunded","unknown_card","currency_not_supported","amt_over_max","amt_under_min","mobile_block","email_block","ip_block","bin_block","device_block","user_block","account_block","risk_block","duplicate_trx","already_chargedback","too_old_to_refund","no_partial_refund","partial_refund_over","redirect","redirect_timeout","processing","routing_error","system_error","psp_error","bad_request","other"],"description":"Harmonized response codes"},"extStatusCode":{"type":"string"},"statusMessage":{"type":"string"},"redirectUrl":{"type":"string","format":"uri"}},"required":["id"],"additionalProperties":false,"description":"API response schema for payment"}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}}}},"/api/v1/payment/card/cancel":{"post":{"description":"Cancels a payment transaction.","summary":"Cancel a transaction","tags":["payments"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"callbackUrl":{"description":"URL to receive webhook callback with transaction result","type":"string","format":"uri"},"manualOverride":{"description":"Operator-only. When true, the provider is not called and the transaction is forced to a successful, manually-approved outcome. Honored only for authenticated operator (user) requests.","type":"boolean"}},"required":["id"]}}}},"responses":{"200":{"description":"API response schema for payment","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"txAmount":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"additionalProperties":false,"description":"Monetary amount with currency"},"txFee":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"additionalProperties":false,"description":"Monetary amount with currency"},"txRefId":{"type":"string","maxLength":255},"state":{"type":"string","enum":["success","processing","waiting","approval","declined","unknown","error","cancelled"],"description":"Payment transaction state"},"statusCode":{"type":"string","enum":["approved","manually_approved","do_not_honor","suspected_fraud","invalid_trx","invalid_amt","invalid_account","invalid_response","no_transaction","restricted_card","insufficient_funds","expired_card","trx_not_permitted","exceeds_limit","exceeds_frequency","invalid_cvv","issuer_err","dest_not_found","psp_malfunction","unable_to_authorize","3ds_auth_failure","psp_limits_reached","psp_timeout","user_aborted_trx","avs_response","no_auth_corresponding","already_captured","already_cancelled","already_refunded","unknown_card","currency_not_supported","amt_over_max","amt_under_min","mobile_block","email_block","ip_block","bin_block","device_block","user_block","account_block","risk_block","duplicate_trx","already_chargedback","too_old_to_refund","no_partial_refund","partial_refund_over","redirect","redirect_timeout","processing","routing_error","system_error","psp_error","bad_request","other"],"description":"Harmonized response codes"},"extStatusCode":{"type":"string"},"statusMessage":{"type":"string"},"redirectUrl":{"type":"string","format":"uri"}},"required":["id"],"additionalProperties":false,"description":"API response schema for payment"}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}}}},"/api/v1/payment/card/chargeback":{"post":{"description":"Records a chargeback against a settled transaction. Most providers do not expose a chargeback API, so this is typically used with manual override.","summary":"Charge back a transaction","tags":["payments"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"callbackUrl":{"description":"URL to receive webhook callback with transaction result","type":"string","format":"uri"},"manualOverride":{"description":"Operator-only. When true, the provider is not called and the transaction is forced to a successful, manually-approved outcome. Honored only for authenticated operator (user) requests.","type":"boolean"}},"required":["id"]}}}},"responses":{"200":{"description":"API response schema for payment","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"txAmount":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"additionalProperties":false,"description":"Monetary amount with currency"},"txFee":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"additionalProperties":false,"description":"Monetary amount with currency"},"txRefId":{"type":"string","maxLength":255},"state":{"type":"string","enum":["success","processing","waiting","approval","declined","unknown","error","cancelled"],"description":"Payment transaction state"},"statusCode":{"type":"string","enum":["approved","manually_approved","do_not_honor","suspected_fraud","invalid_trx","invalid_amt","invalid_account","invalid_response","no_transaction","restricted_card","insufficient_funds","expired_card","trx_not_permitted","exceeds_limit","exceeds_frequency","invalid_cvv","issuer_err","dest_not_found","psp_malfunction","unable_to_authorize","3ds_auth_failure","psp_limits_reached","psp_timeout","user_aborted_trx","avs_response","no_auth_corresponding","already_captured","already_cancelled","already_refunded","unknown_card","currency_not_supported","amt_over_max","amt_under_min","mobile_block","email_block","ip_block","bin_block","device_block","user_block","account_block","risk_block","duplicate_trx","already_chargedback","too_old_to_refund","no_partial_refund","partial_refund_over","redirect","redirect_timeout","processing","routing_error","system_error","psp_error","bad_request","other"],"description":"Harmonized response codes"},"extStatusCode":{"type":"string"},"statusMessage":{"type":"string"},"redirectUrl":{"type":"string","format":"uri"}},"required":["id"],"additionalProperties":false,"description":"API response schema for payment"}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}}}},"/api/v1/payment/status/{id}":{"get":{"description":"Get the status of a payment transaction by its ID.","summary":"Get payment status","tags":["payments"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API response schema for payment","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"txAmount":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"additionalProperties":false,"description":"Monetary amount with currency"},"txFee":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"additionalProperties":false,"description":"Monetary amount with currency"},"txRefId":{"type":"string","maxLength":255},"state":{"type":"string","enum":["success","processing","waiting","approval","declined","unknown","error","cancelled"],"description":"Payment transaction state"},"statusCode":{"type":"string","enum":["approved","manually_approved","do_not_honor","suspected_fraud","invalid_trx","invalid_amt","invalid_account","invalid_response","no_transaction","restricted_card","insufficient_funds","expired_card","trx_not_permitted","exceeds_limit","exceeds_frequency","invalid_cvv","issuer_err","dest_not_found","psp_malfunction","unable_to_authorize","3ds_auth_failure","psp_limits_reached","psp_timeout","user_aborted_trx","avs_response","no_auth_corresponding","already_captured","already_cancelled","already_refunded","unknown_card","currency_not_supported","amt_over_max","amt_under_min","mobile_block","email_block","ip_block","bin_block","device_block","user_block","account_block","risk_block","duplicate_trx","already_chargedback","too_old_to_refund","no_partial_refund","partial_refund_over","redirect","redirect_timeout","processing","routing_error","system_error","psp_error","bad_request","other"],"description":"Harmonized response codes"},"extStatusCode":{"type":"string"},"statusMessage":{"type":"string"},"redirectUrl":{"type":"string","format":"uri"}},"required":["id"],"additionalProperties":false,"description":"API response schema for payment"}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}}}},"/api/v1/payment/checkout-tokens":{"post":{"description":"Creates a checkout API client token for use with checkout API.","summary":"Create checkout API client token","tags":["payments"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"appId":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[a-z0-9-]+$","description":"Application slug ID"},"expiresIn":{"default":300,"description":"Token expiry in seconds (default 5 minutes)","type":"integer","minimum":60,"maximum":3600},"allowedOrigins":{"maxItems":10,"type":"array","items":{"type":"string"},"description":"List of allowed origins for CORS and Origin header enforcement. The browser SDK must send requests from one of these origins."},"metadata":{"description":"Optional metadata","type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"string"}},"txRefId":{"description":"External transaction reference ID","type":"string","maxLength":255},"user":{"type":"object","properties":{"userId":{"type":"string","minLength":1,"maxLength":100},"firstName":{"type":"string","minLength":1,"maxLength":100},"middleName":{"type":"string","minLength":1,"maxLength":100},"lastName":{"type":"string","minLength":1,"maxLength":100},"email":{"type":"string","maxLength":500,"format":"email","pattern":"^(?!\\.)(?!.*\\.\\.)([A-Za-z0-9_'+\\-\\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$","description":"Email"},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$","description":"Phone number in E.164 format"},"dateOfBirth":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Date of birth in YYYY-MM-DD format"},"address":{"type":"object","properties":{"line1":{"type":"string","maxLength":200},"line2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":100},"state":{"type":"string","maxLength":100},"postalCode":{"type":"string","maxLength":20},"countryCode":{"type":"string","enum":["AFG","ALA","ALB","DZA","ASM","AND","AGO","AIA","ATA","ATG","ARG","ARM","ABW","AUS","AUT","AZE","BHS","BHR","BGD","BRB","BLR","BEL","BLZ","BEN","BMU","BTN","BOL","BES","BIH","BWA","BVT","BRA","IOT","VGB","BRN","BGR","BFA","BDI","KHM","CMR","CAN","CPV","CYM","CAF","TCD","CHL","CHN","CXR","CCK","COL","COM","COG","COD","COK","CRI","CIV","HRV","CUB","CUW","CYP","CZE","DNK","DJI","DMA","DOM","ECU","EGY","SLV","GNQ","ERI","EST","SWZ","ETH","FLK","FRO","FJI","FIN","FRA","GUF","PYF","ATF","GAB","GMB","GEO","DEU","GHA","GIB","GRC","GRL","GRD","GLP","GUM","GTM","GGY","GIN","GNB","GUY","HTI","HMD","HND","HKG","HUN","ISL","IND","IDN","IRN","IRQ","IRL","IMN","ISR","ITA","JAM","JPN","JEY","JOR","KAZ","KEN","KIR","PRK","KOR","KWT","KGZ","LAO","LVA","LBN","LSO","LBR","LBY","LIE","LTU","LUX","MAC","MKD","MDG","MWI","MYS","MDV","MLI","MLT","MHL","MTQ","MRT","MUS","MYT","MEX","FSM","MDA","MCO","MNG","MNE","MSR","MAR","MOZ","MMR","NAM","NRU","NPL","NLD","NCL","NZL","NIC","NER","NGA","NIU","NFK","MNP","NOR","OMN","PAK","PLW","PSE","PAN","PNG","PRY","PER","PHL","PCN","POL","PRT","PRI","QAT","REU","ROU","RUS","RWA","BLM","SHN","KNA","LCA","MAF","SPM","VCT","WSM","SMR","STP","SAU","SEN","SRB","SYC","SLE","SGP","SXM","SVK","SVN","SLB","SOM","ZAF","SGS","SSD","ESP","LKA","SDN","SUR","SJM","SWE","CHE","SYR","TWN","TJK","TZA","THA","TLS","TGO","TKL","TON","TTO","TUN","TUR","TKM","TCA","TUV","UGA","UKR","ARE","GBR","USA","UMI","VIR","URY","UZB","VUT","VAT","VEN","VNM","WLF","ESH","YEM","ZMB","ZWE","ZZZ"]}},"required":["line1","city","postalCode","countryCode"],"description":"Address"},"shippingAddress":{"type":"object","properties":{"line1":{"type":"string","maxLength":200},"line2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":100},"state":{"type":"string","maxLength":100},"postalCode":{"type":"string","maxLength":20},"countryCode":{"type":"string","enum":["AFG","ALA","ALB","DZA","ASM","AND","AGO","AIA","ATA","ATG","ARG","ARM","ABW","AUS","AUT","AZE","BHS","BHR","BGD","BRB","BLR","BEL","BLZ","BEN","BMU","BTN","BOL","BES","BIH","BWA","BVT","BRA","IOT","VGB","BRN","BGR","BFA","BDI","KHM","CMR","CAN","CPV","CYM","CAF","TCD","CHL","CHN","CXR","CCK","COL","COM","COG","COD","COK","CRI","CIV","HRV","CUB","CUW","CYP","CZE","DNK","DJI","DMA","DOM","ECU","EGY","SLV","GNQ","ERI","EST","SWZ","ETH","FLK","FRO","FJI","FIN","FRA","GUF","PYF","ATF","GAB","GMB","GEO","DEU","GHA","GIB","GRC","GRL","GRD","GLP","GUM","GTM","GGY","GIN","GNB","GUY","HTI","HMD","HND","HKG","HUN","ISL","IND","IDN","IRN","IRQ","IRL","IMN","ISR","ITA","JAM","JPN","JEY","JOR","KAZ","KEN","KIR","PRK","KOR","KWT","KGZ","LAO","LVA","LBN","LSO","LBR","LBY","LIE","LTU","LUX","MAC","MKD","MDG","MWI","MYS","MDV","MLI","MLT","MHL","MTQ","MRT","MUS","MYT","MEX","FSM","MDA","MCO","MNG","MNE","MSR","MAR","MOZ","MMR","NAM","NRU","NPL","NLD","NCL","NZL","NIC","NER","NGA","NIU","NFK","MNP","NOR","OMN","PAK","PLW","PSE","PAN","PNG","PRY","PER","PHL","PCN","POL","PRT","PRI","QAT","REU","ROU","RUS","RWA","BLM","SHN","KNA","LCA","MAF","SPM","VCT","WSM","SMR","STP","SAU","SEN","SRB","SYC","SLE","SGP","SXM","SVK","SVN","SLB","SOM","ZAF","SGS","SSD","ESP","LKA","SDN","SUR","SJM","SWE","CHE","SYR","TWN","TJK","TZA","THA","TLS","TGO","TKL","TON","TTO","TUN","TUR","TKM","TCA","TUV","UGA","UKR","ARE","GBR","USA","UMI","VIR","URY","UZB","VUT","VAT","VEN","VNM","WLF","ESH","YEM","ZMB","ZWE","ZZZ"]}},"required":["line1","city","postalCode","countryCode"],"description":"Address"}},"required":["firstName","lastName"],"description":"User details for the payment"},"successUrl":{"type":"string","format":"uri"},"failureUrl":{"type":"string","format":"uri"},"callbackUrl":{"type":"string","format":"uri"},"checkoutUrl":{"description":"If true, the response includes a fully-qualified checkout URL that can be used to redirect or embed the hosted checkout.","type":"boolean"},"amount":{"description":"Payment amount. When set, the amount is locked into the session and cannot be changed on the client side.","type":"object","properties":{"amt":{"type":"number","exclusiveMinimum":0,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"]},"embedMode":{"description":"Embedding mode for the hosted checkout. Included in the checkout URL when checkoutUrl is true.","type":"string","enum":["redirect","iframe"]},"parentOrigin":{"description":"Origin of the merchant page embedding the checkout (iframe). Included in the checkout URL when checkoutUrl is true.","type":"string"}},"required":["appId","allowedOrigins","user"],"description":"Request schema for creating a checkout token"}}}},"responses":{"200":{"description":"Response schema for checkout token creation","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"Checkout token"},"expiresAt":{"type":"string","description":"Token expiry timestamp in ISO format"},"allowedOrigins":{"type":"array","items":{"type":"string"},"description":"Allowed origins bound to this session token"},"url":{"description":"Fully-qualified hosted checkout URL. Only present when the request set checkoutUrl=true.","type":"string","format":"uri"}},"required":["token","expiresAt","allowedOrigins"],"additionalProperties":false,"description":"Response schema for checkout token creation"}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}}}},"/api/v1/checkout/options":{"get":{"description":"Returns a list of available payment options with their required fields.","summary":"List available payment options","tags":["checkout"],"parameters":[],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["card-debit-new","card-debit-token","card-credit-token","open-banking-debit"],"description":"Payment option type identifier"},"fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Field name"},"type":{"type":"string","enum":["string","number","boolean"],"description":"Field type"},"required":{"type":"boolean","description":"Whether the field is required"},"label":{"type":"string","description":"Display label for the field"},"placeholder":{"description":"Placeholder text","type":"string"},"regex":{"description":"Validation regex pattern","type":"string"}},"required":["name","type","required","label"],"additionalProperties":false,"description":"Schema for a payment option field"},"description":"Fields required for this payment option"},"icon":{"description":"Icon URL or name","type":"string"}},"required":["type","fields"],"additionalProperties":false,"description":"Schema for a payment option"}}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}}}},"/api/v1/checkout/debit":{"post":{"description":"Processes a debit payment using the checkout API.","summary":"Process debit payment","tags":["checkout"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"amount":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"description":"Amount to process"},"txRefId":{"description":"External transaction reference ID","type":"string","maxLength":255},"paymentType":{"type":"string","const":"card-debit-new"},"encCardNumber":{"type":"string","minLength":1,"maxLength":256,"description":"Encrypted card number"},"encCvv":{"type":"string","minLength":1,"maxLength":256,"description":"Encrypted CVV"},"expiryMonth":{"type":"integer","minimum":1,"maximum":12,"description":"Card expiry month (1-12)"},"expiryYear":{"type":"integer","minimum":1970,"maximum":2100,"description":"Card expiry year (4 digits)"},"cardholderName":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-zÀ-ÖØ-öø-ÿ'\\- ]+$","description":"Name of the cardholder as it appears on the card"},"save":{"description":"Save card for future payments","type":"boolean"}},"required":["amount","paymentType","encCardNumber","encCvv","expiryMonth","expiryYear","cardholderName"],"description":"Checkout payload for a new card debit"},{"type":"object","properties":{"amount":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"description":"Amount to process"},"txRefId":{"description":"External transaction reference ID","type":"string","maxLength":255},"paymentType":{"type":"string","const":"card-debit-token"},"tokenId":{"type":"string","minLength":1,"maxLength":256,"description":"Encrypted card number"},"encCvv":{"type":"string","minLength":1,"maxLength":256,"description":"Encrypted CVV"},"expiryMonth":{"type":"integer","minimum":1,"maximum":12,"description":"Card expiry month (1-12)"},"expiryYear":{"type":"integer","minimum":1970,"maximum":2100,"description":"Card expiry year (4 digits)"}},"required":["amount","paymentType","tokenId","encCvv"],"description":"Checkout payload for a tokenized card debit"},{"type":"object","properties":{"amount":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"description":"Amount to process"},"txRefId":{"description":"External transaction reference ID","type":"string","maxLength":255},"paymentType":{"type":"string","const":"open-banking-debit"}},"required":["amount","paymentType"],"description":"Checkout payload for an open banking debit"}],"description":"Request schema for checkout debit"}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"txAmount":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"additionalProperties":false,"description":"Monetary amount with currency"},"txRefId":{"type":"string","maxLength":255},"state":{"type":"string","enum":["success","processing","waiting","approval","declined","unknown","error","cancelled"],"description":"Payment transaction state"},"statusCode":{"type":"string","enum":["approved","manually_approved","do_not_honor","suspected_fraud","invalid_trx","invalid_amt","invalid_account","invalid_response","no_transaction","restricted_card","insufficient_funds","expired_card","trx_not_permitted","exceeds_limit","exceeds_frequency","invalid_cvv","issuer_err","dest_not_found","psp_malfunction","unable_to_authorize","3ds_auth_failure","psp_limits_reached","psp_timeout","user_aborted_trx","avs_response","no_auth_corresponding","already_captured","already_cancelled","already_refunded","unknown_card","currency_not_supported","amt_over_max","amt_under_min","mobile_block","email_block","ip_block","bin_block","device_block","user_block","account_block","risk_block","duplicate_trx","already_chargedback","too_old_to_refund","no_partial_refund","partial_refund_over","redirect","redirect_timeout","processing","routing_error","system_error","psp_error","bad_request","other"],"description":"Harmonized response codes"},"extStatusCode":{"type":"string"},"redirectUrl":{"type":"string","format":"uri"}},"required":["id"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}}}},"/api/v1/checkout/credit":{"post":{"description":"Processes a credit payment using the checkout API.","summary":"Process credit payment","tags":["checkout"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"amount":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"description":"Amount to process"},"txRefId":{"description":"External transaction reference ID","type":"string","maxLength":255},"paymentType":{"type":"string","const":"card-credit-token"},"encCardNumber":{"type":"string","minLength":1,"maxLength":256,"description":"Encrypted card number"}},"required":["amount","paymentType","encCardNumber"],"description":"Checkout payload for a tokenized card credit"}],"description":"Request schema for checkout credit"}}}},"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"txAmount":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"additionalProperties":false,"description":"Monetary amount with currency"},"txRefId":{"type":"string","maxLength":255},"state":{"type":"string","enum":["success","processing","waiting","approval","declined","unknown","error","cancelled"],"description":"Payment transaction state"},"statusCode":{"type":"string","enum":["approved","manually_approved","do_not_honor","suspected_fraud","invalid_trx","invalid_amt","invalid_account","invalid_response","no_transaction","restricted_card","insufficient_funds","expired_card","trx_not_permitted","exceeds_limit","exceeds_frequency","invalid_cvv","issuer_err","dest_not_found","psp_malfunction","unable_to_authorize","3ds_auth_failure","psp_limits_reached","psp_timeout","user_aborted_trx","avs_response","no_auth_corresponding","already_captured","already_cancelled","already_refunded","unknown_card","currency_not_supported","amt_over_max","amt_under_min","mobile_block","email_block","ip_block","bin_block","device_block","user_block","account_block","risk_block","duplicate_trx","already_chargedback","too_old_to_refund","no_partial_refund","partial_refund_over","redirect","redirect_timeout","processing","routing_error","system_error","psp_error","bad_request","other"],"description":"Harmonized response codes"},"extStatusCode":{"type":"string"},"redirectUrl":{"type":"string","format":"uri"}},"required":["id"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}}}},"/api/v1/checkout/status/{id}":{"get":{"description":"Get the status of a checkout payment transaction by its ID.","summary":"Get payment status","tags":["checkout"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"txAmount":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"additionalProperties":false,"description":"Monetary amount with currency"},"txRefId":{"type":"string","maxLength":255},"state":{"type":"string","enum":["success","processing","waiting","approval","declined","unknown","error","cancelled"],"description":"Payment transaction state"},"statusCode":{"type":"string","enum":["approved","manually_approved","do_not_honor","suspected_fraud","invalid_trx","invalid_amt","invalid_account","invalid_response","no_transaction","restricted_card","insufficient_funds","expired_card","trx_not_permitted","exceeds_limit","exceeds_frequency","invalid_cvv","issuer_err","dest_not_found","psp_malfunction","unable_to_authorize","3ds_auth_failure","psp_limits_reached","psp_timeout","user_aborted_trx","avs_response","no_auth_corresponding","already_captured","already_cancelled","already_refunded","unknown_card","currency_not_supported","amt_over_max","amt_under_min","mobile_block","email_block","ip_block","bin_block","device_block","user_block","account_block","risk_block","duplicate_trx","already_chargedback","too_old_to_refund","no_partial_refund","partial_refund_over","redirect","redirect_timeout","processing","routing_error","system_error","psp_error","bad_request","other"],"description":"Harmonized response codes"},"extStatusCode":{"type":"string"},"redirectUrl":{"type":"string","format":"uri"}},"required":["id"],"additionalProperties":false}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}}}},"/api/v1/checkout/revoke/{tokenId}":{"delete":{"description":"Marks a saved card as revoked and removes encrypted data.","summary":"Revoke a saved card","tags":["checkout"],"parameters":[{"name":"tokenId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Response schema for checkout revoke","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the revocation was successful"}},"required":["success"],"additionalProperties":false,"description":"Response schema for checkout revoke"}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"],"additionalProperties":false}}}}}}}},"info":{"title":"API – Payment","version":"1.0.0"},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}}},"security":[{"BearerAuth":[]}],"servers":[{"url":"https://api-sandbox.babelpay.io","description":"Current environment"}],"webhooks":{"paymentCallback":{"post":{"summary":"Payment webhook callback","description":"**Note: Never trust the callback data without signature verification!** The callback is sent to the callbackUrl provided in the payment request when the transaction reaches a final state. Delivered with up to 3 retries.\n\n## Signature verification\n\nEvery webhook request includes two headers for signature verification:\n\n| Header | Description |\n| --- | --- |\n| `X-Webhook-Signature` | `sha256=<hex-encoded HMAC-SHA256>` |\n| `X-Webhook-Timestamp` | Unix epoch seconds when the request was signed |\n\nThe HMAC is computed over `{timestamp}.{raw JSON body}` using the `webhookSecret` (`whsec_…`) returned when the API key was created.\n\n### Verification steps\n\n1. Read `X-Webhook-Timestamp` and `X-Webhook-Signature` from the request headers.\n2. Reject the request if the timestamp is more than 5 minutes old (replay protection).\n3. Concatenate `{timestamp}.{raw request body}` (UTF-8).\n4. Compute `HMAC-SHA256(webhookSecret, concatenated string)` and hex-encode the result.\n5. Compare with the signature value after the `sha256=` prefix using a constant-time comparison.\n\n### Quick test — TypeScript Playground\n\nPaste the snippet below into [TypeScript Playground](https://www.typescriptlang.org/play), fill in the three values from an actual webhook request, and check the **Logs** tab.\n\n```typescript\n// ---- paste your values here ----\nconst webhookSecret    = \"whsec_...\";           // from API key creation\nconst signatureHeader  = \"sha256=...\";          // X-Webhook-Signature header\nconst timestampHeader  = \"1717344000\";          // X-Webhook-Timestamp header\nconst rawBody          = '{\"id\":\"...\"}';       // raw JSON body\n\n// ---- verify ----\n(async () => {\n  const enc = new TextEncoder();\n  const key = await crypto.subtle.importKey(\n    \"raw\", enc.encode(webhookSecret),\n    { name: \"HMAC\", hash: \"SHA-256\" }, false, [\"sign\"],\n  );\n  const sig = await crypto.subtle.sign(\n    \"HMAC\", key, enc.encode(`${timestampHeader}.${rawBody}`),\n  );\n  const expected = Array.from(new Uint8Array(sig))\n    .map(b => b.toString(16).padStart(2, \"0\")).join(\"\");\n  const received = signatureHeader.replace(/^sha256=/, \"\");\n\n  console.log(\"Expected:\", expected);\n  console.log(\"Received:\", received);\n  console.log(\"Valid:\", expected === received);\n})();\n```\n","requestBody":{"description":"The webhook callback payload containing the payment result.","required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"txAmount":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"additionalProperties":false,"description":"Monetary amount with currency"},"txFee":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"additionalProperties":false,"description":"Monetary amount with currency"},"txRefId":{"type":"string","maxLength":255},"state":{"type":"string","enum":["success","processing","waiting","approval","declined","unknown","error","cancelled"],"description":"Payment transaction state"},"statusCode":{"type":"string","enum":["approved","manually_approved","do_not_honor","suspected_fraud","invalid_trx","invalid_amt","invalid_account","invalid_response","no_transaction","restricted_card","insufficient_funds","expired_card","trx_not_permitted","exceeds_limit","exceeds_frequency","invalid_cvv","issuer_err","dest_not_found","psp_malfunction","unable_to_authorize","3ds_auth_failure","psp_limits_reached","psp_timeout","user_aborted_trx","avs_response","no_auth_corresponding","already_captured","already_cancelled","already_refunded","unknown_card","currency_not_supported","amt_over_max","amt_under_min","mobile_block","email_block","ip_block","bin_block","device_block","user_block","account_block","risk_block","duplicate_trx","already_chargedback","too_old_to_refund","no_partial_refund","partial_refund_over","redirect","redirect_timeout","processing","routing_error","system_error","psp_error","bad_request","other"],"description":"Harmonized response codes"},"extStatusCode":{"type":"string"},"statusMessage":{"type":"string"},"redirectUrl":{"type":"string","format":"uri"}},"required":["id"],"additionalProperties":false,"description":"Webhook callback payload sent to the customer callbackUrl"}}}},"parameters":[{"name":"X-Webhook-Signature","in":"header","required":false,"description":"HMAC-SHA256 signature: `sha256=<hex>`","schema":{"type":"string","example":"sha256=a1b2c3d4..."}},{"name":"X-Webhook-Timestamp","in":"header","required":false,"description":"Unix epoch seconds when the signature was computed","schema":{"type":"string","example":"1717344000"}}],"responses":{"200":{"description":"Callback received successfully. Any 2xx response is treated as success."}}}}}}