{"openapi":"3.1.0","paths":{"/api/v2/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":["payment"],"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":{"description":"Decimal amount as a canonical string","type":["string","number"]},"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":"Monetary amount with currency"},"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"]},"browser":{"type":"object","properties":{"acceptHeader":{"description":"HTTP Accept header sent by the shopper's browser","type":"string","maxLength":2048},"language":{"description":"Browser language per BCP 47 (navigator.language), e.g. en-US","type":"string","minLength":1,"maxLength":35},"javaEnabled":{"description":"Whether Java is enabled (navigator.javaEnabled())","type":"boolean"},"javaScriptEnabled":{"description":"Whether JavaScript is enabled in the shopper's browser","type":"boolean"},"colorDepth":{"description":"Screen colour depth in bits per pixel (screen.colorDepth)","type":"integer","minimum":1,"maximum":48},"screenHeight":{"description":"Screen height in pixels (screen.height)","type":"integer","minimum":0,"maximum":999999},"screenWidth":{"description":"Screen width in pixels (screen.width)","type":"integer","minimum":0,"maximum":999999},"timeZoneOffset":{"description":"Minutes between UTC and browser local time, as returned by Date.getTimezoneOffset() — e.g. 300 for UTC-5, -120 for UTC+2","type":"integer","minimum":-840,"maximum":840}},"description":"Shopper browser details for EMV 3DS device data"}},"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":{"description":"Phone number in E.164 format; separators (spaces, hyphens, dots, parentheses) are accepted and stripped","type":"string","maxLength":50},"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,"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"},"threeDS":{"type":"object","properties":{"version":{"type":"string"},"eci":{"type":"string"},"cavv":{"type":"string"},"dsTransactionId":{"type":"string"},"xid":{"type":"string"},"transStatus":{"type":"string"},"enrolled":{"type":"string"}},"description":"External 3-D Secure authentication result"}},"required":["appId","amount","device","txRefId","card"],"example":{"appId":"towl-test-app","amount":{"amt":"24.42","cy":"EUR"},"device":{"ip":"203.0.113.7"},"user":{"userId":"DontPanic42","firstName":"Arthur","lastName":"Dent","email":"arthur.dent@example.com","phone":"+46701234567","address":{"line1":"Handduksvagen 42","city":"Stockholm","postalCode":"11122","countryCode":"SWE"}},"txRefId":"order-10442","card":{"cardNumber":"4242424242424242","expiryMonth":12,"expiryYear":2030,"cardHolderName":"Arthur Dent","cardBrand":"VISA"},"callbackUrl":"https://your-server.com/webhooks/payment-callback"}}}}},"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":"string","pattern":"^-?(?:0|[1-9][0-9]{0,17})(?:\\.[0-9]{0,17}[1-9])?$","description":"Decimal amount as a canonical string"},"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, amount as a canonical decimal string"},"txFee":{"type":"object","properties":{"amt":{"type":"string","pattern":"^-?(?:0|[1-9][0-9]{0,17})(?:\\.[0-9]{0,17}[1-9])?$","description":"Decimal amount as a canonical string"},"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, amount as a canonical decimal string"},"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","psp_routing_error","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","blocked","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,"example":{"id":"9f4b2c1a-7d3e-4a6b-9c2d-1e8f5a7b3c4d","txAmount":{"amt":"24.42","cy":"EUR"},"txRefId":"order-10442","state":"success","statusCode":"approved","statusMessage":"Approved"}}}}},"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/v2/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":["payment"],"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":{"description":"Decimal amount as a canonical string","type":["string","number"]},"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":"Monetary amount with currency"},"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"]},"browser":{"type":"object","properties":{"acceptHeader":{"description":"HTTP Accept header sent by the shopper's browser","type":"string","maxLength":2048},"language":{"description":"Browser language per BCP 47 (navigator.language), e.g. en-US","type":"string","minLength":1,"maxLength":35},"javaEnabled":{"description":"Whether Java is enabled (navigator.javaEnabled())","type":"boolean"},"javaScriptEnabled":{"description":"Whether JavaScript is enabled in the shopper's browser","type":"boolean"},"colorDepth":{"description":"Screen colour depth in bits per pixel (screen.colorDepth)","type":"integer","minimum":1,"maximum":48},"screenHeight":{"description":"Screen height in pixels (screen.height)","type":"integer","minimum":0,"maximum":999999},"screenWidth":{"description":"Screen width in pixels (screen.width)","type":"integer","minimum":0,"maximum":999999},"timeZoneOffset":{"description":"Minutes between UTC and browser local time, as returned by Date.getTimezoneOffset() — e.g. 300 for UTC-5, -120 for UTC+2","type":"integer","minimum":-840,"maximum":840}},"description":"Shopper browser details for EMV 3DS device data"}},"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":{"description":"Phone number in E.164 format; separators (spaces, hyphens, dots, parentheses) are accepted and stripped","type":"string","maxLength":50},"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,"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"},"threeDS":{"type":"object","properties":{"version":{"type":"string"},"eci":{"type":"string"},"cavv":{"type":"string"},"dsTransactionId":{"type":"string"},"xid":{"type":"string"},"transStatus":{"type":"string"},"enrolled":{"type":"string"}},"description":"External 3-D Secure authentication result"}},"required":["appId","amount","device","txRefId","card"],"example":{"appId":"towl-test-app","amount":{"amt":"24.42","cy":"EUR"},"device":{"ip":"203.0.113.7"},"user":{"userId":"DontPanic42","firstName":"Arthur","lastName":"Dent","email":"arthur.dent@example.com","phone":"+46701234567","address":{"line1":"Handduksvagen 42","city":"Stockholm","postalCode":"11122","countryCode":"SWE"}},"txRefId":"order-10442","card":{"cardNumber":"4242424242424242","expiryMonth":12,"expiryYear":2030,"cardHolderName":"Arthur Dent","cardBrand":"VISA"},"callbackUrl":"https://your-server.com/webhooks/payment-callback"}}}}},"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":"string","pattern":"^-?(?:0|[1-9][0-9]{0,17})(?:\\.[0-9]{0,17}[1-9])?$","description":"Decimal amount as a canonical string"},"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, amount as a canonical decimal string"},"txFee":{"type":"object","properties":{"amt":{"type":"string","pattern":"^-?(?:0|[1-9][0-9]{0,17})(?:\\.[0-9]{0,17}[1-9])?$","description":"Decimal amount as a canonical string"},"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, amount as a canonical decimal string"},"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","psp_routing_error","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","blocked","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,"example":{"id":"9f4b2c1a-7d3e-4a6b-9c2d-1e8f5a7b3c4d","txAmount":{"amt":"24.42","cy":"EUR"},"txRefId":"order-10442","state":"success","statusCode":"approved","statusMessage":"Approved"}}}}},"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/v2/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":["payment"],"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":{"description":"Decimal amount as a canonical string","type":["string","number"]},"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":"Monetary amount with currency"},"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"]},"browser":{"type":"object","properties":{"acceptHeader":{"description":"HTTP Accept header sent by the shopper's browser","type":"string","maxLength":2048},"language":{"description":"Browser language per BCP 47 (navigator.language), e.g. en-US","type":"string","minLength":1,"maxLength":35},"javaEnabled":{"description":"Whether Java is enabled (navigator.javaEnabled())","type":"boolean"},"javaScriptEnabled":{"description":"Whether JavaScript is enabled in the shopper's browser","type":"boolean"},"colorDepth":{"description":"Screen colour depth in bits per pixel (screen.colorDepth)","type":"integer","minimum":1,"maximum":48},"screenHeight":{"description":"Screen height in pixels (screen.height)","type":"integer","minimum":0,"maximum":999999},"screenWidth":{"description":"Screen width in pixels (screen.width)","type":"integer","minimum":0,"maximum":999999},"timeZoneOffset":{"description":"Minutes between UTC and browser local time, as returned by Date.getTimezoneOffset() — e.g. 300 for UTC-5, -120 for UTC+2","type":"integer","minimum":-840,"maximum":840}},"description":"Shopper browser details for EMV 3DS device data"}},"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":{"description":"Phone number in E.164 format; separators (spaces, hyphens, dots, parentheses) are accepted and stripped","type":"string","maxLength":50},"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,"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"],"example":{"appId":"towl-test-app","amount":{"amt":"50","cy":"EUR"},"device":{"ip":"203.0.113.7"},"user":{"userId":"DontPanic42","firstName":"Arthur","lastName":"Dent","email":"arthur.dent@example.com","phone":"+46701234567","address":{"line1":"Handduksvagen 42","city":"Stockholm","postalCode":"11122","countryCode":"SWE"}},"txRefId":"payout-20881","card":{"cardNumber":"4242424242424242","expiryMonth":12,"expiryYear":2030,"cardHolderName":"Arthur Dent","cardBrand":"VISA"},"callbackUrl":"https://your-server.com/webhooks/payment-callback"}}}}},"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":"string","pattern":"^-?(?:0|[1-9][0-9]{0,17})(?:\\.[0-9]{0,17}[1-9])?$","description":"Decimal amount as a canonical string"},"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, amount as a canonical decimal string"},"txFee":{"type":"object","properties":{"amt":{"type":"string","pattern":"^-?(?:0|[1-9][0-9]{0,17})(?:\\.[0-9]{0,17}[1-9])?$","description":"Decimal amount as a canonical string"},"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, amount as a canonical decimal string"},"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","psp_routing_error","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","blocked","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,"example":{"id":"9f4b2c1a-7d3e-4a6b-9c2d-1e8f5a7b3c4d","txAmount":{"amt":"24.42","cy":"EUR"},"txRefId":"order-10442","state":"success","statusCode":"approved","statusMessage":"Approved"}}}}},"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/v2/payment/card/refund":{"post":{"description":"Refunds a previously captured charge.","summary":"Refund a charge","tags":["payment"],"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"},"attemptNo":{"description":"Operator-only. Target an attempt the failover cascade walked away from, instead of the provider the transaction row names. Its index in the transaction's routing attempt trail, as reported by the reconciliation finding for that attempt. This is how a payment left live at an abandoned provider — a double charge, or an authorization nothing will settle — is voided or refunded at the provider actually holding it. Honored only for authenticated operator (user) requests.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["id"],"example":{"id":"9f4b2c1a-7d3e-4a6b-9c2d-1e8f5a7b3c4d","callbackUrl":"https://your-server.com/webhooks/payment-callback"}}}}},"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":"string","pattern":"^-?(?:0|[1-9][0-9]{0,17})(?:\\.[0-9]{0,17}[1-9])?$","description":"Decimal amount as a canonical string"},"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, amount as a canonical decimal string"},"txFee":{"type":"object","properties":{"amt":{"type":"string","pattern":"^-?(?:0|[1-9][0-9]{0,17})(?:\\.[0-9]{0,17}[1-9])?$","description":"Decimal amount as a canonical string"},"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, amount as a canonical decimal string"},"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","psp_routing_error","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","blocked","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,"example":{"id":"9f4b2c1a-7d3e-4a6b-9c2d-1e8f5a7b3c4d","txAmount":{"amt":"24.42","cy":"EUR"},"txRefId":"order-10442","state":"success","statusCode":"approved","statusMessage":"Approved"}}}}},"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/v2/payment/card/void":{"post":{"description":"Cancels an authorization hold without capturing.","summary":"Void an authorization","tags":["payment"],"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"},"attemptNo":{"description":"Operator-only. Target an attempt the failover cascade walked away from, instead of the provider the transaction row names. Its index in the transaction's routing attempt trail, as reported by the reconciliation finding for that attempt. This is how a payment left live at an abandoned provider — a double charge, or an authorization nothing will settle — is voided or refunded at the provider actually holding it. Honored only for authenticated operator (user) requests.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["id"],"example":{"id":"9f4b2c1a-7d3e-4a6b-9c2d-1e8f5a7b3c4d","callbackUrl":"https://your-server.com/webhooks/payment-callback"}}}}},"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":"string","pattern":"^-?(?:0|[1-9][0-9]{0,17})(?:\\.[0-9]{0,17}[1-9])?$","description":"Decimal amount as a canonical string"},"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, amount as a canonical decimal string"},"txFee":{"type":"object","properties":{"amt":{"type":"string","pattern":"^-?(?:0|[1-9][0-9]{0,17})(?:\\.[0-9]{0,17}[1-9])?$","description":"Decimal amount as a canonical string"},"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, amount as a canonical decimal string"},"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","psp_routing_error","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","blocked","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,"example":{"id":"9f4b2c1a-7d3e-4a6b-9c2d-1e8f5a7b3c4d","txAmount":{"amt":"24.42","cy":"EUR"},"txRefId":"order-10442","state":"success","statusCode":"approved","statusMessage":"Approved"}}}}},"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/v2/payment/card/capture":{"post":{"description":"Captures funds from a previously authorized charge.","summary":"Capture an authorization","tags":["payment"],"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"},"attemptNo":{"description":"Operator-only. Target an attempt the failover cascade walked away from, instead of the provider the transaction row names. Its index in the transaction's routing attempt trail, as reported by the reconciliation finding for that attempt. This is how a payment left live at an abandoned provider — a double charge, or an authorization nothing will settle — is voided or refunded at the provider actually holding it. Honored only for authenticated operator (user) requests.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["id"],"example":{"id":"9f4b2c1a-7d3e-4a6b-9c2d-1e8f5a7b3c4d","callbackUrl":"https://your-server.com/webhooks/payment-callback"}}}}},"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":"string","pattern":"^-?(?:0|[1-9][0-9]{0,17})(?:\\.[0-9]{0,17}[1-9])?$","description":"Decimal amount as a canonical string"},"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, amount as a canonical decimal string"},"txFee":{"type":"object","properties":{"amt":{"type":"string","pattern":"^-?(?:0|[1-9][0-9]{0,17})(?:\\.[0-9]{0,17}[1-9])?$","description":"Decimal amount as a canonical string"},"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, amount as a canonical decimal string"},"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","psp_routing_error","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","blocked","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,"example":{"id":"9f4b2c1a-7d3e-4a6b-9c2d-1e8f5a7b3c4d","txAmount":{"amt":"24.42","cy":"EUR"},"txRefId":"order-10442","state":"success","statusCode":"approved","statusMessage":"Approved"}}}}},"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/v2/payment/card/cancel":{"post":{"description":"Cancels a payment transaction.","summary":"Cancel a transaction","tags":["payment"],"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"},"attemptNo":{"description":"Operator-only. Target an attempt the failover cascade walked away from, instead of the provider the transaction row names. Its index in the transaction's routing attempt trail, as reported by the reconciliation finding for that attempt. This is how a payment left live at an abandoned provider — a double charge, or an authorization nothing will settle — is voided or refunded at the provider actually holding it. Honored only for authenticated operator (user) requests.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["id"],"example":{"id":"9f4b2c1a-7d3e-4a6b-9c2d-1e8f5a7b3c4d","callbackUrl":"https://your-server.com/webhooks/payment-callback"}}}}},"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":"string","pattern":"^-?(?:0|[1-9][0-9]{0,17})(?:\\.[0-9]{0,17}[1-9])?$","description":"Decimal amount as a canonical string"},"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, amount as a canonical decimal string"},"txFee":{"type":"object","properties":{"amt":{"type":"string","pattern":"^-?(?:0|[1-9][0-9]{0,17})(?:\\.[0-9]{0,17}[1-9])?$","description":"Decimal amount as a canonical string"},"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, amount as a canonical decimal string"},"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","psp_routing_error","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","blocked","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,"example":{"id":"9f4b2c1a-7d3e-4a6b-9c2d-1e8f5a7b3c4d","txAmount":{"amt":"24.42","cy":"EUR"},"txRefId":"order-10442","state":"success","statusCode":"approved","statusMessage":"Approved"}}}}},"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/v2/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":["payment"],"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"},"attemptNo":{"description":"Operator-only. Target an attempt the failover cascade walked away from, instead of the provider the transaction row names. Its index in the transaction's routing attempt trail, as reported by the reconciliation finding for that attempt. This is how a payment left live at an abandoned provider — a double charge, or an authorization nothing will settle — is voided or refunded at the provider actually holding it. Honored only for authenticated operator (user) requests.","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},"required":["id"],"example":{"id":"9f4b2c1a-7d3e-4a6b-9c2d-1e8f5a7b3c4d","callbackUrl":"https://your-server.com/webhooks/payment-callback"}}}}},"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":"string","pattern":"^-?(?:0|[1-9][0-9]{0,17})(?:\\.[0-9]{0,17}[1-9])?$","description":"Decimal amount as a canonical string"},"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, amount as a canonical decimal string"},"txFee":{"type":"object","properties":{"amt":{"type":"string","pattern":"^-?(?:0|[1-9][0-9]{0,17})(?:\\.[0-9]{0,17}[1-9])?$","description":"Decimal amount as a canonical string"},"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, amount as a canonical decimal string"},"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","psp_routing_error","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","blocked","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,"example":{"id":"9f4b2c1a-7d3e-4a6b-9c2d-1e8f5a7b3c4d","txAmount":{"amt":"24.42","cy":"EUR"},"txRefId":"order-10442","state":"success","statusCode":"approved","statusMessage":"Approved"}}}}},"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/v2/payment/status/{id}":{"get":{"description":"Get the status of a payment transaction by its ID.","summary":"Get payment status","tags":["payment"],"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":"string","pattern":"^-?(?:0|[1-9][0-9]{0,17})(?:\\.[0-9]{0,17}[1-9])?$","description":"Decimal amount as a canonical string"},"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, amount as a canonical decimal string"},"txFee":{"type":"object","properties":{"amt":{"type":"string","pattern":"^-?(?:0|[1-9][0-9]{0,17})(?:\\.[0-9]{0,17}[1-9])?$","description":"Decimal amount as a canonical string"},"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, amount as a canonical decimal string"},"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","psp_routing_error","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","blocked","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,"example":{"id":"9f4b2c1a-7d3e-4a6b-9c2d-1e8f5a7b3c4d","txAmount":{"amt":"24.42","cy":"EUR"},"txRefId":"order-10442","state":"success","statusCode":"approved","statusMessage":"Approved"}}}}},"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/v2/payment/checkout-tokens":{"post":{"description":"Creates a checkout API client token for use with checkout API.\n\nSee the **[Checkout API guide](/api/docs/checkout-api)** for the full end-to-end flow (minting tokens, options, debit, status polling, appearance/styling).","summary":"Create checkout API client token","tags":["payment"],"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":{"description":"Phone number in E.164 format; separators (spaces, hyphens, dots, parentheses) are accepted and stripped","type":"string","maxLength":50},"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":{"type":"object","properties":{"amt":{"description":"Decimal amount as a canonical string","type":["string","number"]},"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":"Monetary amount with currency"},"direction":{"description":"Which way money moves in this session: `debit` (from the shopper — a payment, the default) or `credit` (to the shopper — a withdrawal/payout). Frozen into the session: `POST /api/v1/checkout/credit` only accepts sessions minted with `credit`, and the options list follows the session's direction. A `credit` session requires `amount` — a payout amount is never taken from the browser.","type":"string","enum":["debit","credit"]},"paymentOption":{"description":"Pre-select a single payment option. The hosted checkout then skips the option list and opens that option directly — submitting straight away when it needs no input from the shopper, or showing only its own fields when it does. Included in the checkout URL when checkoutUrl is true.","type":"string","enum":["card","ideal","bancontact","paypal","klarna","pay-by-bank","apple-pay","google-pay","crypto-onramp","crypto-accept"]},"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"},"appearance":{"description":"Appearance overrides for this checkout session. Resolved and frozen at token creation; applies to the hosted checkout (redirect and iframe) and to Card SDK fields created with this session's token.","type":"object","properties":{"colors":{"type":"object","properties":{"background":{"description":"Page background","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"},"surface":{"description":"Main card background","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"},"surfaceElevated":{"description":"Inputs / chips background","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"},"border":{"description":"Default border color","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"},"borderHighlight":{"description":"Hover / focus border color","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"},"textPrimary":{"description":"Primary text","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"},"textSecondary":{"description":"Secondary text","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"},"textMuted":{"description":"Muted text / placeholders","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"},"accent":{"description":"Accent (pay button, highlights)","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"},"accentSecondary":{"description":"Second accent gradient stop. Defaults to `accent` when omitted, producing a solid button.","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"},"danger":{"description":"Error text / borders","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"},"success":{"description":"Success text / icons","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"}},"additionalProperties":false},"logoUrl":{"description":"Merchant logo shown above the checkout card (https only)","type":"string","maxLength":2048,"format":"uri","pattern":"^https:\\/\\/.*"},"cornerRadius":{"description":"Corner-radius scale for cards, inputs and buttons (default md)","type":"string","enum":["none","sm","md","lg"]},"fontFamily":{"description":"Font stack. System font stacks only — the checkout CSP does not allow external font loading.","type":"string","enum":["system","serif","mono","rounded"]},"customCss":{"description":"Raw CSS appended after the theme (sanitized: `@import`, external url() references and markup are stripped). Requires checkoutCustomCssEnabled on the organization.","type":"string","maxLength":50000},"styleUrl":{"description":"URL of a CSS file fetched ONCE at token creation, sanitized and frozen into the session (snapshot-at-mint). Requires checkoutCustomCssEnabled on the organization.","type":"string","maxLength":2048,"format":"uri","pattern":"^https:\\/\\/.*"}},"additionalProperties":false,"example":{"colors":{"background":"#101014","surface":"#1c1c24","accent":"#e8590c","textPrimary":"#ffffff"},"logoUrl":"https://your-domain.com/logo.svg","cornerRadius":"lg","fontFamily":"system"}}},"required":["appId","allowedOrigins","user"]}}}},"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. Its path carries the API version of the request that minted the session — a session created on `/api/v2/...` gets a `/v2/` checkout URL — so the whole payment stays on the version you integrated against.","type":"string","format":"uri"}},"required":["token","expiresAt","allowedOrigins"],"additionalProperties":false,"description":"Response schema for checkout token creation","example":{"token":"ck_a1b2c3d4-e5f6-7890-abcd-ef1234567890","expiresAt":"2026-08-04T11:00:00.000Z","allowedOrigins":["https://your-domain.com"],"url":"https://checkout.wardenpay.com/v2/ck_a1b2c3d4-e5f6-7890-abcd-ef1234567890?amount=24.42&currency=EUR&embedMode=iframe"}}}}},"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/v2/checkout/options":{"get":{"description":"Amounts follow the API version of the key that minted the checkout session, the same as the server API — the current version sends `{\"amt\": \"24.42\"}` as a decimal string, older ones send a JSON number. Requests accept either. Returns a list of available payment options with their required fields. Which direction they are for is the session's to decide: a session minted with `direction: \"credit\"` lists payout options (stored-card credits, derived from the session user's saved cards), and any other session lists payment options. There is no request parameter for this — the `ck_` token travels in a URL the shopper can edit, so letting the request choose would offer payout methods that `POST /checkout/credit` then refuses.","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","ideal-debit","bancontact-debit","paypal-debit","klarna-debit","pay-by-bank-debit","applepay-debit","googlepay-debit","crypto-onramp-debit","crypto-accept-debit"],"description":"Payment option type identifier"},"paymentOption":{"description":"Canonical PSP-independent payment option this entry belongs to","type":"string","enum":["card","ideal","bancontact","paypal","klarna","pay-by-bank","apple-pay","google-pay","crypto-onramp","crypto-accept"]},"displayName":{"description":"User-facing display name. Always the payment option — never the underlying gateway.","type":"string"},"flow":{"description":"How the option is completed: inline card entry, a redirect that continues in the payment method's own page, or a device-wallet sheet raised in the checkout page itself.","type":"string","enum":["inline-card","redirect","wallet"]},"redirectDisplay":{"description":"How a redirect-flow option's provider page is displayed: in the checkout overlay iframe, or a popup handoff (bank/wallet pages routinely refuse framing via X-Frame-Options).","type":"string","enum":["iframe","popup"]},"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"},"wallet":{"description":"Setup for a `wallet`-flow option's sheet, filled in by the routed provider","type":"object","properties":{"environment":{"type":"string","enum":["TEST","PRODUCTION"],"description":"Wallet environment the provider's credentials belong to"},"merchantName":{"type":"string","maxLength":128,"description":"Name the sheet shows the shopper as the payee"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"Merchant country, ISO 3166-1 alpha-2"},"supportedNetworks":{"minItems":1,"type":"array","items":{"type":"string","maxLength":32},"description":"Card networks the processor accepts, in the wallet's vocabulary"},"merchantCapabilities":{"description":"Apple Pay merchant capabilities (e.g. supports3DS)","type":"array","items":{"type":"string","maxLength":32}},"allowedAuthMethods":{"description":"Google Pay auth methods (e.g. PAN_ONLY, CRYPTOGRAM_3DS)","type":"array","items":{"type":"string","maxLength":32}},"gateway":{"description":"Google Pay gateway identifier — opaque to the checkout","type":"string","maxLength":64},"gatewayMerchantId":{"description":"Google Pay gateway merchant id — opaque to the checkout","type":"string","maxLength":128},"merchantId":{"description":"Google Pay merchant id issued by Google, required in PRODUCTION","type":"string","maxLength":128},"requiresMerchantSession":{"description":"Apple Pay: the page must call POST /checkout/wallet/session to validate the merchant before the sheet can proceed","type":"boolean"}},"required":["environment","merchantName","countryCode","supportedNetworks"],"additionalProperties":false}},"required":["type","fields"],"additionalProperties":false,"description":"Schema for a payment option"},"example":[{"type":"card-debit-new","paymentOption":"card","displayName":"Card","flow":"inline-card","fields":[{"name":"encCardNumber","type":"string","required":true,"label":"Card number"},{"name":"encCvv","type":"string","required":true,"label":"CVV"},{"name":"expiryMonth","type":"number","required":true,"label":"Expiry month"},{"name":"expiryYear","type":"number","required":true,"label":"Expiry year"},{"name":"cardholderName","type":"string","required":false,"label":"Cardholder name"}]},{"type":"card-debit-token","paymentOption":"card","displayName":"Saved card","flow":"inline-card","fields":[{"name":"encCvv","type":"string","required":true,"label":"CVV"}],"icon":"{\"tokenId\":\"tok_7f3a…\",\"maskedCard\":\"424242••••4242\",\"expiryMonth\":\"12\",\"expiryYear\":\"2030\",\"cardBrand\":\"VISA\"}"},{"type":"ideal-debit","paymentOption":"ideal","displayName":"iDEAL","flow":"redirect","fields":[],"icon":"ideal"}]}}}},"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/v2/checkout/appearance":{"get":{"description":"Returns the merchant appearance (design tokens and snapshotted custom CSS) frozen into this checkout session at token creation. Empty object when the session has no appearance overrides.","summary":"Get session appearance","tags":["checkout"],"parameters":[],"responses":{"200":{"description":"Resolved appearance for the current checkout session","content":{"application/json":{"schema":{"type":"object","properties":{"colors":{"type":"object","properties":{"background":{"description":"Page background","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"},"surface":{"description":"Main card background","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"},"surfaceElevated":{"description":"Inputs / chips background","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"},"border":{"description":"Default border color","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"},"borderHighlight":{"description":"Hover / focus border color","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"},"textPrimary":{"description":"Primary text","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"},"textSecondary":{"description":"Secondary text","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"},"textMuted":{"description":"Muted text / placeholders","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"},"accent":{"description":"Accent (pay button, highlights)","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"},"accentSecondary":{"description":"Second accent gradient stop. Defaults to `accent` when omitted, producing a solid button.","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"},"danger":{"description":"Error text / borders","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"},"success":{"description":"Success text / icons","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"}},"additionalProperties":false},"logoUrl":{"description":"Merchant logo shown above the checkout card (https only)","type":"string","maxLength":2048,"format":"uri","pattern":"^https:\\/\\/.*"},"cornerRadius":{"description":"Corner-radius scale for cards, inputs and buttons (default md)","type":"string","enum":["none","sm","md","lg"]},"fontFamily":{"description":"Font stack. System font stacks only — the checkout CSP does not allow external font loading.","type":"string","enum":["system","serif","mono","rounded"]},"customCss":{"description":"Raw CSS appended after the theme (sanitized: `@import`, external url() references and markup are stripped). Requires checkoutCustomCssEnabled on the organization.","type":"string","maxLength":50000}},"additionalProperties":false,"description":"Resolved appearance for the current checkout session","example":{"colors":{"background":"#101014","surface":"#1c1c24","accent":"#e8590c","textPrimary":"#ffffff"},"logoUrl":"https://your-domain.com/logo.svg","cornerRadius":"lg","fontFamily":"system"}}}}},"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/v2/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},"browser":{"description":"EMV 3DS browser data collected on the checkout page","type":"object","properties":{"acceptHeader":{"description":"HTTP Accept header sent by the shopper's browser","type":"string","maxLength":2048},"language":{"description":"Browser language per BCP 47 (navigator.language), e.g. en-US","type":"string","minLength":1,"maxLength":35},"javaEnabled":{"description":"Whether Java is enabled (navigator.javaEnabled())","type":"boolean"},"javaScriptEnabled":{"description":"Whether JavaScript is enabled in the shopper's browser","type":"boolean"},"colorDepth":{"description":"Screen colour depth in bits per pixel (screen.colorDepth)","type":"integer","minimum":1,"maximum":48},"screenHeight":{"description":"Screen height in pixels (screen.height)","type":"integer","minimum":0,"maximum":999999},"screenWidth":{"description":"Screen width in pixels (screen.width)","type":"integer","minimum":0,"maximum":999999},"timeZoneOffset":{"description":"Minutes between UTC and browser local time, as returned by Date.getTimezoneOffset() — e.g. 300 for UTC-5, -120 for UTC+2","type":"integer","minimum":-840,"maximum":840},"userAgent":{"description":"Shopper's User-Agent header, stamped by the checkout worker","type":"string","maxLength":2048}}},"themeHint":{"description":"Theme the checkout page resolved at submit time (see CheckoutThemeHintSchema)","type":"object","properties":{"colorScheme":{"description":"Colour scheme the checkout resolved for itself","type":"string","enum":["light","dark"]},"background":{"description":"Background the checkout's opaque surfaces paint","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"}}},"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,"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},"browser":{"description":"EMV 3DS browser data collected on the checkout page","type":"object","properties":{"acceptHeader":{"description":"HTTP Accept header sent by the shopper's browser","type":"string","maxLength":2048},"language":{"description":"Browser language per BCP 47 (navigator.language), e.g. en-US","type":"string","minLength":1,"maxLength":35},"javaEnabled":{"description":"Whether Java is enabled (navigator.javaEnabled())","type":"boolean"},"javaScriptEnabled":{"description":"Whether JavaScript is enabled in the shopper's browser","type":"boolean"},"colorDepth":{"description":"Screen colour depth in bits per pixel (screen.colorDepth)","type":"integer","minimum":1,"maximum":48},"screenHeight":{"description":"Screen height in pixels (screen.height)","type":"integer","minimum":0,"maximum":999999},"screenWidth":{"description":"Screen width in pixels (screen.width)","type":"integer","minimum":0,"maximum":999999},"timeZoneOffset":{"description":"Minutes between UTC and browser local time, as returned by Date.getTimezoneOffset() — e.g. 300 for UTC-5, -120 for UTC+2","type":"integer","minimum":-840,"maximum":840},"userAgent":{"description":"Shopper's User-Agent header, stamped by the checkout worker","type":"string","maxLength":2048}}},"themeHint":{"description":"Theme the checkout page resolved at submit time (see CheckoutThemeHintSchema)","type":"object","properties":{"colorScheme":{"description":"Colour scheme the checkout resolved for itself","type":"string","enum":["light","dark"]},"background":{"description":"Background the checkout's opaque surfaces paint","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"}}},"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},"browser":{"description":"EMV 3DS browser data collected on the checkout page","type":"object","properties":{"acceptHeader":{"description":"HTTP Accept header sent by the shopper's browser","type":"string","maxLength":2048},"language":{"description":"Browser language per BCP 47 (navigator.language), e.g. en-US","type":"string","minLength":1,"maxLength":35},"javaEnabled":{"description":"Whether Java is enabled (navigator.javaEnabled())","type":"boolean"},"javaScriptEnabled":{"description":"Whether JavaScript is enabled in the shopper's browser","type":"boolean"},"colorDepth":{"description":"Screen colour depth in bits per pixel (screen.colorDepth)","type":"integer","minimum":1,"maximum":48},"screenHeight":{"description":"Screen height in pixels (screen.height)","type":"integer","minimum":0,"maximum":999999},"screenWidth":{"description":"Screen width in pixels (screen.width)","type":"integer","minimum":0,"maximum":999999},"timeZoneOffset":{"description":"Minutes between UTC and browser local time, as returned by Date.getTimezoneOffset() — e.g. 300 for UTC-5, -120 for UTC+2","type":"integer","minimum":-840,"maximum":840},"userAgent":{"description":"Shopper's User-Agent header, stamped by the checkout worker","type":"string","maxLength":2048}}},"themeHint":{"description":"Theme the checkout page resolved at submit time (see CheckoutThemeHintSchema)","type":"object","properties":{"colorScheme":{"description":"Colour scheme the checkout resolved for itself","type":"string","enum":["light","dark"]},"background":{"description":"Background the checkout's opaque surfaces paint","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"}}},"paymentType":{"type":"string","const":"ideal-debit"}},"required":["amount","paymentType"],"description":"Checkout payload for an iDEAL 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},"browser":{"description":"EMV 3DS browser data collected on the checkout page","type":"object","properties":{"acceptHeader":{"description":"HTTP Accept header sent by the shopper's browser","type":"string","maxLength":2048},"language":{"description":"Browser language per BCP 47 (navigator.language), e.g. en-US","type":"string","minLength":1,"maxLength":35},"javaEnabled":{"description":"Whether Java is enabled (navigator.javaEnabled())","type":"boolean"},"javaScriptEnabled":{"description":"Whether JavaScript is enabled in the shopper's browser","type":"boolean"},"colorDepth":{"description":"Screen colour depth in bits per pixel (screen.colorDepth)","type":"integer","minimum":1,"maximum":48},"screenHeight":{"description":"Screen height in pixels (screen.height)","type":"integer","minimum":0,"maximum":999999},"screenWidth":{"description":"Screen width in pixels (screen.width)","type":"integer","minimum":0,"maximum":999999},"timeZoneOffset":{"description":"Minutes between UTC and browser local time, as returned by Date.getTimezoneOffset() — e.g. 300 for UTC-5, -120 for UTC+2","type":"integer","minimum":-840,"maximum":840},"userAgent":{"description":"Shopper's User-Agent header, stamped by the checkout worker","type":"string","maxLength":2048}}},"themeHint":{"description":"Theme the checkout page resolved at submit time (see CheckoutThemeHintSchema)","type":"object","properties":{"colorScheme":{"description":"Colour scheme the checkout resolved for itself","type":"string","enum":["light","dark"]},"background":{"description":"Background the checkout's opaque surfaces paint","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"}}},"paymentType":{"type":"string","const":"bancontact-debit"}},"required":["amount","paymentType"],"description":"Checkout payload for a Bancontact 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},"browser":{"description":"EMV 3DS browser data collected on the checkout page","type":"object","properties":{"acceptHeader":{"description":"HTTP Accept header sent by the shopper's browser","type":"string","maxLength":2048},"language":{"description":"Browser language per BCP 47 (navigator.language), e.g. en-US","type":"string","minLength":1,"maxLength":35},"javaEnabled":{"description":"Whether Java is enabled (navigator.javaEnabled())","type":"boolean"},"javaScriptEnabled":{"description":"Whether JavaScript is enabled in the shopper's browser","type":"boolean"},"colorDepth":{"description":"Screen colour depth in bits per pixel (screen.colorDepth)","type":"integer","minimum":1,"maximum":48},"screenHeight":{"description":"Screen height in pixels (screen.height)","type":"integer","minimum":0,"maximum":999999},"screenWidth":{"description":"Screen width in pixels (screen.width)","type":"integer","minimum":0,"maximum":999999},"timeZoneOffset":{"description":"Minutes between UTC and browser local time, as returned by Date.getTimezoneOffset() — e.g. 300 for UTC-5, -120 for UTC+2","type":"integer","minimum":-840,"maximum":840},"userAgent":{"description":"Shopper's User-Agent header, stamped by the checkout worker","type":"string","maxLength":2048}}},"themeHint":{"description":"Theme the checkout page resolved at submit time (see CheckoutThemeHintSchema)","type":"object","properties":{"colorScheme":{"description":"Colour scheme the checkout resolved for itself","type":"string","enum":["light","dark"]},"background":{"description":"Background the checkout's opaque surfaces paint","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"}}},"paymentType":{"type":"string","const":"paypal-debit"}},"required":["amount","paymentType"],"description":"Checkout payload for a PayPal 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},"browser":{"description":"EMV 3DS browser data collected on the checkout page","type":"object","properties":{"acceptHeader":{"description":"HTTP Accept header sent by the shopper's browser","type":"string","maxLength":2048},"language":{"description":"Browser language per BCP 47 (navigator.language), e.g. en-US","type":"string","minLength":1,"maxLength":35},"javaEnabled":{"description":"Whether Java is enabled (navigator.javaEnabled())","type":"boolean"},"javaScriptEnabled":{"description":"Whether JavaScript is enabled in the shopper's browser","type":"boolean"},"colorDepth":{"description":"Screen colour depth in bits per pixel (screen.colorDepth)","type":"integer","minimum":1,"maximum":48},"screenHeight":{"description":"Screen height in pixels (screen.height)","type":"integer","minimum":0,"maximum":999999},"screenWidth":{"description":"Screen width in pixels (screen.width)","type":"integer","minimum":0,"maximum":999999},"timeZoneOffset":{"description":"Minutes between UTC and browser local time, as returned by Date.getTimezoneOffset() — e.g. 300 for UTC-5, -120 for UTC+2","type":"integer","minimum":-840,"maximum":840},"userAgent":{"description":"Shopper's User-Agent header, stamped by the checkout worker","type":"string","maxLength":2048}}},"themeHint":{"description":"Theme the checkout page resolved at submit time (see CheckoutThemeHintSchema)","type":"object","properties":{"colorScheme":{"description":"Colour scheme the checkout resolved for itself","type":"string","enum":["light","dark"]},"background":{"description":"Background the checkout's opaque surfaces paint","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"}}},"paymentType":{"type":"string","const":"klarna-debit"}},"required":["amount","paymentType"],"description":"Checkout payload for a Klarna 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},"browser":{"description":"EMV 3DS browser data collected on the checkout page","type":"object","properties":{"acceptHeader":{"description":"HTTP Accept header sent by the shopper's browser","type":"string","maxLength":2048},"language":{"description":"Browser language per BCP 47 (navigator.language), e.g. en-US","type":"string","minLength":1,"maxLength":35},"javaEnabled":{"description":"Whether Java is enabled (navigator.javaEnabled())","type":"boolean"},"javaScriptEnabled":{"description":"Whether JavaScript is enabled in the shopper's browser","type":"boolean"},"colorDepth":{"description":"Screen colour depth in bits per pixel (screen.colorDepth)","type":"integer","minimum":1,"maximum":48},"screenHeight":{"description":"Screen height in pixels (screen.height)","type":"integer","minimum":0,"maximum":999999},"screenWidth":{"description":"Screen width in pixels (screen.width)","type":"integer","minimum":0,"maximum":999999},"timeZoneOffset":{"description":"Minutes between UTC and browser local time, as returned by Date.getTimezoneOffset() — e.g. 300 for UTC-5, -120 for UTC+2","type":"integer","minimum":-840,"maximum":840},"userAgent":{"description":"Shopper's User-Agent header, stamped by the checkout worker","type":"string","maxLength":2048}}},"themeHint":{"description":"Theme the checkout page resolved at submit time (see CheckoutThemeHintSchema)","type":"object","properties":{"colorScheme":{"description":"Colour scheme the checkout resolved for itself","type":"string","enum":["light","dark"]},"background":{"description":"Background the checkout's opaque surfaces paint","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"}}},"paymentType":{"type":"string","const":"pay-by-bank-debit"},"country":{"description":"Bank country","type":"string","minLength":2,"maxLength":2}},"required":["amount","paymentType"],"description":"Checkout payload for a Pay by Bank (open banking) 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},"browser":{"description":"EMV 3DS browser data collected on the checkout page","type":"object","properties":{"acceptHeader":{"description":"HTTP Accept header sent by the shopper's browser","type":"string","maxLength":2048},"language":{"description":"Browser language per BCP 47 (navigator.language), e.g. en-US","type":"string","minLength":1,"maxLength":35},"javaEnabled":{"description":"Whether Java is enabled (navigator.javaEnabled())","type":"boolean"},"javaScriptEnabled":{"description":"Whether JavaScript is enabled in the shopper's browser","type":"boolean"},"colorDepth":{"description":"Screen colour depth in bits per pixel (screen.colorDepth)","type":"integer","minimum":1,"maximum":48},"screenHeight":{"description":"Screen height in pixels (screen.height)","type":"integer","minimum":0,"maximum":999999},"screenWidth":{"description":"Screen width in pixels (screen.width)","type":"integer","minimum":0,"maximum":999999},"timeZoneOffset":{"description":"Minutes between UTC and browser local time, as returned by Date.getTimezoneOffset() — e.g. 300 for UTC-5, -120 for UTC+2","type":"integer","minimum":-840,"maximum":840},"userAgent":{"description":"Shopper's User-Agent header, stamped by the checkout worker","type":"string","maxLength":2048}}},"themeHint":{"description":"Theme the checkout page resolved at submit time (see CheckoutThemeHintSchema)","type":"object","properties":{"colorScheme":{"description":"Colour scheme the checkout resolved for itself","type":"string","enum":["light","dark"]},"background":{"description":"Background the checkout's opaque surfaces paint","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"}}},"paymentType":{"type":"string","const":"applepay-debit"},"wallet":{"type":"object","properties":{"token":{"type":"string","minLength":1,"maxLength":65536,"description":"Opaque, processor-encrypted wallet payment token"},"network":{"description":"Card network the wallet reported","type":"string","maxLength":32},"lastFour":{"description":"Last four of the device account number","type":"string","maxLength":4},"displayName":{"description":"Card description the wallet showed the shopper","type":"string","maxLength":64}},"required":["token"],"description":"Payment credential returned by a device wallet"}},"required":["amount","paymentType"],"description":"Checkout payload for an Apple Pay 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},"browser":{"description":"EMV 3DS browser data collected on the checkout page","type":"object","properties":{"acceptHeader":{"description":"HTTP Accept header sent by the shopper's browser","type":"string","maxLength":2048},"language":{"description":"Browser language per BCP 47 (navigator.language), e.g. en-US","type":"string","minLength":1,"maxLength":35},"javaEnabled":{"description":"Whether Java is enabled (navigator.javaEnabled())","type":"boolean"},"javaScriptEnabled":{"description":"Whether JavaScript is enabled in the shopper's browser","type":"boolean"},"colorDepth":{"description":"Screen colour depth in bits per pixel (screen.colorDepth)","type":"integer","minimum":1,"maximum":48},"screenHeight":{"description":"Screen height in pixels (screen.height)","type":"integer","minimum":0,"maximum":999999},"screenWidth":{"description":"Screen width in pixels (screen.width)","type":"integer","minimum":0,"maximum":999999},"timeZoneOffset":{"description":"Minutes between UTC and browser local time, as returned by Date.getTimezoneOffset() — e.g. 300 for UTC-5, -120 for UTC+2","type":"integer","minimum":-840,"maximum":840},"userAgent":{"description":"Shopper's User-Agent header, stamped by the checkout worker","type":"string","maxLength":2048}}},"themeHint":{"description":"Theme the checkout page resolved at submit time (see CheckoutThemeHintSchema)","type":"object","properties":{"colorScheme":{"description":"Colour scheme the checkout resolved for itself","type":"string","enum":["light","dark"]},"background":{"description":"Background the checkout's opaque surfaces paint","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"}}},"paymentType":{"type":"string","const":"googlepay-debit"},"wallet":{"type":"object","properties":{"token":{"type":"string","minLength":1,"maxLength":65536,"description":"Opaque, processor-encrypted wallet payment token"},"network":{"description":"Card network the wallet reported","type":"string","maxLength":32},"lastFour":{"description":"Last four of the device account number","type":"string","maxLength":4},"displayName":{"description":"Card description the wallet showed the shopper","type":"string","maxLength":64}},"required":["token"],"description":"Payment credential returned by a device wallet"}},"required":["amount","paymentType"],"description":"Checkout payload for a Google Pay 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},"browser":{"description":"EMV 3DS browser data collected on the checkout page","type":"object","properties":{"acceptHeader":{"description":"HTTP Accept header sent by the shopper's browser","type":"string","maxLength":2048},"language":{"description":"Browser language per BCP 47 (navigator.language), e.g. en-US","type":"string","minLength":1,"maxLength":35},"javaEnabled":{"description":"Whether Java is enabled (navigator.javaEnabled())","type":"boolean"},"javaScriptEnabled":{"description":"Whether JavaScript is enabled in the shopper's browser","type":"boolean"},"colorDepth":{"description":"Screen colour depth in bits per pixel (screen.colorDepth)","type":"integer","minimum":1,"maximum":48},"screenHeight":{"description":"Screen height in pixels (screen.height)","type":"integer","minimum":0,"maximum":999999},"screenWidth":{"description":"Screen width in pixels (screen.width)","type":"integer","minimum":0,"maximum":999999},"timeZoneOffset":{"description":"Minutes between UTC and browser local time, as returned by Date.getTimezoneOffset() — e.g. 300 for UTC-5, -120 for UTC+2","type":"integer","minimum":-840,"maximum":840},"userAgent":{"description":"Shopper's User-Agent header, stamped by the checkout worker","type":"string","maxLength":2048}}},"themeHint":{"description":"Theme the checkout page resolved at submit time (see CheckoutThemeHintSchema)","type":"object","properties":{"colorScheme":{"description":"Colour scheme the checkout resolved for itself","type":"string","enum":["light","dark"]},"background":{"description":"Background the checkout's opaque surfaces paint","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"}}},"paymentType":{"type":"string","const":"crypto-onramp-debit"}},"required":["amount","paymentType"],"description":"Checkout payload for a crypto onramp 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},"browser":{"description":"EMV 3DS browser data collected on the checkout page","type":"object","properties":{"acceptHeader":{"description":"HTTP Accept header sent by the shopper's browser","type":"string","maxLength":2048},"language":{"description":"Browser language per BCP 47 (navigator.language), e.g. en-US","type":"string","minLength":1,"maxLength":35},"javaEnabled":{"description":"Whether Java is enabled (navigator.javaEnabled())","type":"boolean"},"javaScriptEnabled":{"description":"Whether JavaScript is enabled in the shopper's browser","type":"boolean"},"colorDepth":{"description":"Screen colour depth in bits per pixel (screen.colorDepth)","type":"integer","minimum":1,"maximum":48},"screenHeight":{"description":"Screen height in pixels (screen.height)","type":"integer","minimum":0,"maximum":999999},"screenWidth":{"description":"Screen width in pixels (screen.width)","type":"integer","minimum":0,"maximum":999999},"timeZoneOffset":{"description":"Minutes between UTC and browser local time, as returned by Date.getTimezoneOffset() — e.g. 300 for UTC-5, -120 for UTC+2","type":"integer","minimum":-840,"maximum":840},"userAgent":{"description":"Shopper's User-Agent header, stamped by the checkout worker","type":"string","maxLength":2048}}},"themeHint":{"description":"Theme the checkout page resolved at submit time (see CheckoutThemeHintSchema)","type":"object","properties":{"colorScheme":{"description":"Colour scheme the checkout resolved for itself","type":"string","enum":["light","dark"]},"background":{"description":"Background the checkout's opaque surfaces paint","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"}}},"paymentType":{"type":"string","const":"crypto-accept-debit"}},"required":["amount","paymentType"],"description":"Checkout payload for a crypto (own wallet) debit"}],"description":"Request schema for checkout debit","example":{"paymentType":"card-debit-new","amount":{"amt":"24.42","cy":"EUR"},"encCardNumber":"ev:Tk9D:A7x…:$","encCvv":"ev:Tk9D:Q2v…:$","expiryMonth":12,"expiryYear":2030,"cardholderName":"Arthur Dent","save":true}}}}},"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":"string","pattern":"^-?(?:0|[1-9][0-9]{0,17})(?:\\.[0-9]{0,17}[1-9])?$","description":"Decimal amount as a canonical string"},"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, amount as a canonical decimal string"},"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","psp_routing_error","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","blocked","processing","routing_error","system_error","psp_error","bad_request","other"],"description":"Harmonized response codes"},"redirectUrl":{"type":"string","format":"uri"},"paymentOption":{"type":"string","enum":["card","ideal","bancontact","paypal","klarna","pay-by-bank","apple-pay","google-pay","crypto-onramp","crypto-accept"]}},"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/v2/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},"browser":{"description":"EMV 3DS browser data collected on the checkout page","type":"object","properties":{"acceptHeader":{"description":"HTTP Accept header sent by the shopper's browser","type":"string","maxLength":2048},"language":{"description":"Browser language per BCP 47 (navigator.language), e.g. en-US","type":"string","minLength":1,"maxLength":35},"javaEnabled":{"description":"Whether Java is enabled (navigator.javaEnabled())","type":"boolean"},"javaScriptEnabled":{"description":"Whether JavaScript is enabled in the shopper's browser","type":"boolean"},"colorDepth":{"description":"Screen colour depth in bits per pixel (screen.colorDepth)","type":"integer","minimum":1,"maximum":48},"screenHeight":{"description":"Screen height in pixels (screen.height)","type":"integer","minimum":0,"maximum":999999},"screenWidth":{"description":"Screen width in pixels (screen.width)","type":"integer","minimum":0,"maximum":999999},"timeZoneOffset":{"description":"Minutes between UTC and browser local time, as returned by Date.getTimezoneOffset() — e.g. 300 for UTC-5, -120 for UTC+2","type":"integer","minimum":-840,"maximum":840},"userAgent":{"description":"Shopper's User-Agent header, stamped by the checkout worker","type":"string","maxLength":2048}}},"themeHint":{"description":"Theme the checkout page resolved at submit time (see CheckoutThemeHintSchema)","type":"object","properties":{"colorScheme":{"description":"Colour scheme the checkout resolved for itself","type":"string","enum":["light","dark"]},"background":{"description":"Background the checkout's opaque surfaces paint","type":"string","maxLength":64,"pattern":"^(#[0-9a-fA-F]{3,8}|(?:rgb|rgba|hsl|hsla)\\(\\s*[\\d.,%\\s/]+\\s*\\))$"}}},"paymentType":{"type":"string","const":"card-credit-token"},"tokenId":{"type":"string","minLength":1,"maxLength":256,"description":"Stored card token ID to credit"}},"required":["amount","paymentType","tokenId"],"description":"Checkout payload for a tokenized card credit"}],"description":"Request schema for checkout credit","example":{"paymentType":"card-credit-token","amount":{"amt":"50","cy":"EUR"},"tokenId":"tok_7f3a…","txRefId":"payout-20881"}}}}},"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":"string","pattern":"^-?(?:0|[1-9][0-9]{0,17})(?:\\.[0-9]{0,17}[1-9])?$","description":"Decimal amount as a canonical string"},"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, amount as a canonical decimal string"},"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","psp_routing_error","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","blocked","processing","routing_error","system_error","psp_error","bad_request","other"],"description":"Harmonized response codes"},"redirectUrl":{"type":"string","format":"uri"},"paymentOption":{"type":"string","enum":["card","ideal","bancontact","paypal","klarna","pay-by-bank","apple-pay","google-pay","crypto-onramp","crypto-accept"]}},"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/v2/checkout/wallet/session":{"post":{"description":"Apple Pay asks the page to prove the merchant is entitled to take a payment on this domain, and only the holder of the Apple Pay merchant identity certificate can answer. The page relays the wallet's one-time `validationUrl` here and the provider routed for this session answers with its own certificate, so the checkout never handles wallet credentials of any kind. Returns the merchant session verbatim, for `completeMerchantValidation`. Google Pay needs no such step and is rejected here.","summary":"Validate a device-wallet merchant session","tags":["checkout"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"option":{"type":"string","enum":["apple-pay","google-pay"],"description":"Which wallet is asking"},"validationUrl":{"type":"string","maxLength":512,"format":"uri","description":"Validation URL the wallet supplied"},"initiativeContext":{"description":"Domain the sheet is running on; defaults to the checkout host","type":"string","maxLength":255}},"required":["option","validationUrl"],"description":"Request schema for a wallet merchant session","example":{"option":"apple-pay","validationUrl":"https://apple-pay-gateway.apple.com/paymentservices/paymentSession","initiativeContext":"checkout.wardenpay.com"}}}}},"responses":{"200":{"description":"Response schema for a wallet merchant session","content":{"application/json":{"schema":{"type":"object","properties":{"merchantSession":{"type":"string","description":"Opaque merchant session JSON, passed straight to the wallet"}},"required":["merchantSession"],"additionalProperties":false,"description":"Response schema for a wallet merchant session"}}}},"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/v2/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":"string","pattern":"^-?(?:0|[1-9][0-9]{0,17})(?:\\.[0-9]{0,17}[1-9])?$","description":"Decimal amount as a canonical string"},"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, amount as a canonical decimal string"},"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","psp_routing_error","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","blocked","processing","routing_error","system_error","psp_error","bad_request","other"],"description":"Harmonized response codes"},"redirectUrl":{"type":"string","format":"uri"},"paymentOption":{"type":"string","enum":["card","ideal","bancontact","paypal","klarna","pay-by-bank","apple-pay","google-pay","crypto-onramp","crypto-accept"]}},"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/v2/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","example":{"success":true}}}}},"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 (v2)","version":"2.0.0","description":"The payment API provides endpoints for processing card payments, including authorization, capture, refund, and void operations. It also supports retrieving payment status and managing checkout tokens.\n\n## Versioning\n\nThe version is in the path: `/api/v2/payment/...` is the current one, `/api/v1/payment/...` the previous. Both stay served — we never change the shape of an existing path's responses underneath you.\n\nOnly a breaking change gets a new version. New endpoints, new response fields, new optional request fields and relaxed validation ship without one.\n\n### Your client must tolerate unfamiliar enum values\n\n`statusCode`, `paymentOption` and similar fields gain values as we add providers and map new outcomes, and **this happens without a version change**. Do not switch exhaustively on `statusCode` and fail on the default branch — you will eventually meet a value your build predates.\n\nBranch on `state` instead, which is a small, stable set (`success`, `declined`, `error`, `processing`, `waiting`, `approval`, `cancelled`, `unknown`), and treat `statusCode` as detail for logs, support and reporting. A `statusCode` you do not recognise is never a reason to reject a payment outcome.\n\n### Amounts\n\nv2 sends an amount as a decimal string (`{\"amt\": \"24.42\", \"cy\": \"EUR\"}`). v1 sends a JSON number, which is an IEEE-754 double and cannot represent the 6-, 8- and 18-decimal assets exactly — a single wei is not rounded in a double, it is invisible. Use v2 to settle in those assets, and read `amt` as a string rather than parsing it into a float.\n\nRequests are lenient in both versions: `amt` may be a number or a string, whichever suits your client."},"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer"}}},"security":[{"BearerAuth":[]}],"servers":[{"url":"https://api-dev.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)$"},"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","psp_routing_error","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","blocked","processing","routing_error","system_error","psp_error","bad_request","other"],"description":"Harmonized response codes"},"txAmount":{"type":"object","properties":{"amt":{"type":"string","pattern":"^-?(?:0|[1-9][0-9]{0,17})(?:\\.[0-9]{0,17}[1-9])?$","description":"Decimal amount as a canonical string"},"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, amount as a canonical decimal string"}},"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."}}}}}}