{"openapi":"3.1.0","paths":{"/api/v1/payment/card/auth":{"post":{"description":"Creates an authorization hold on a card for a specified amount without capturing the funds.\n\n## Test Cards\n\n### Approved (no 3DS)\n| PAN | statusCode | responseCode |\n|-----|------------|--------------|\n| 4242424242424242 | approved | 0 |\n| 4111111111111111 | approved | 0 |\n| 5555555555554444 | approved | 0 |\n| 378282246310005 | approved | 0 |\n\n### Approved (3DS challenge)\n| PAN | statusCode | responseCode |\n|-----|------------|--------------|\n| 4000000000003220 | approved | 0 |\n| 4000002500003155 | approved | 0 |\n| 5200828282828210 | approved | 0 |\n\n### Declined\n| PAN | statusCode | responseCode |\n|-----|------------|--------------|\n| 4000000000000002 | do_not_honor | 5 |\n| 4000000000009995 | insufficient_funds | 51 |\n| 4000000000000069 | expired_card | 54 |\n| 4000000000000127 | invalid_cvv | 79 |\n| 4000000000000119 | psp_malfunction | 96 |\n| 4100000000000019 | suspected_fraud | 59 |\n| 4000000000000259 | issuer_err | 91 |\n| 4000000000000341 | 3ds_auth_failure | 103 |\n| 4000000000000051 | psp_timeout | 105 |","summary":"Authorize a card","tags":["payments"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"appId":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[a-z0-9-]+$"},"amount":{"type":"object","properties":{"amt":{"type":"number","minimum":0,"maximum":1000000000,"exclusiveMinimum":0,"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":"Monetary amount with currency"},"device":{"type":"object","properties":{"ip":{"type":"string"},"userAgent":{"type":"string"},"deviceType":{"type":"string","enum":["desktop","mobile","tablet","unknown"]}},"required":["ip"],"description":"Enduser device details"},"user":{"type":"object","properties":{"userId":{"type":"string","minLength":1,"maxLength":100},"firstName":{"type":"string","minLength":1,"maxLength":100},"middleName":{"type":"string","minLength":1,"maxLength":100},"lastName":{"type":"string","minLength":1,"maxLength":100},"email":{"type":"string","format":"email","maxLength":500,"description":"Email"},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$","description":"Phone number in E.164 format"},"dateOfBirth":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Date of birth in YYYY-MM-DD format"},"address":{"type":"object","properties":{"line1":{"type":"string","maxLength":200},"line2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":100},"state":{"type":"string","maxLength":100},"postalCode":{"type":"string","maxLength":20},"countryCode":{"type":"string","enum":["AFG","ALA","ALB","DZA","ASM","AND","AGO","AIA","ATA","ATG","ARG","ARM","ABW","AUS","AUT","AZE","BHS","BHR","BGD","BRB","BLR","BEL","BLZ","BEN","BMU","BTN","BOL","BIH","BWA","BRA","BGR","BFA","BDI","KHM","CMR","CAN","CPV","CAF","TCD","CHL","CHN","COL","COM","COG","COD","CRI","CIV","HRV","CUB","CYP","CZE","DNK","DJI","DMA","DOM","ECU","EGY","SLV","GNQ","ERI","EST","ETH","FJI","FIN","FRA","GAB","GMB","GEO","DEU","GHA","GRC","GRD","GTM","GIN","GNB","GUY","HTI","HND","HKG","HUN","ISL","IND","IDN","IRN","IRQ","IRL","ISR","ITA","JAM","JPN","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","MRT","MUS","MEX","FSM","MDA","MCO","MNG","MNE","MAR","MOZ","MMR","NAM","NRU","NPL","NLD","NZL","NIC","NER","NGA","NOR","OMN","PAK","PLW","PSE","PAN","PNG","PRY","PER","PHL","POL","PRT","QAT","ROU","RUS","RWA","KNA","LCA","VCT","WSM","SMR","STP","SAU","SEN","SRB","SYC","SLE","SGP","SVK","SVN","SLB","SOM","ZAF","SSD","ESP","LKA","SDN","SUR","SWE","CHE","SYR","TWN","TJK","TZA","THA","TLS","TGO","TON","TTO","TUN","TUR","TKM","TUV","UGA","UKR","ARE","GBR","USA","URY","UZB","VUT","VAT","VEN","VNM","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","BIH","BWA","BRA","BGR","BFA","BDI","KHM","CMR","CAN","CPV","CAF","TCD","CHL","CHN","COL","COM","COG","COD","CRI","CIV","HRV","CUB","CYP","CZE","DNK","DJI","DMA","DOM","ECU","EGY","SLV","GNQ","ERI","EST","ETH","FJI","FIN","FRA","GAB","GMB","GEO","DEU","GHA","GRC","GRD","GTM","GIN","GNB","GUY","HTI","HND","HKG","HUN","ISL","IND","IDN","IRN","IRQ","IRL","ISR","ITA","JAM","JPN","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","MRT","MUS","MEX","FSM","MDA","MCO","MNG","MNE","MAR","MOZ","MMR","NAM","NRU","NPL","NLD","NZL","NIC","NER","NGA","NOR","OMN","PAK","PLW","PSE","PAN","PNG","PRY","PER","PHL","POL","PRT","QAT","ROU","RUS","RWA","KNA","LCA","VCT","WSM","SMR","STP","SAU","SEN","SRB","SYC","SLE","SGP","SVK","SVN","SLB","SOM","ZAF","SSD","ESP","LKA","SDN","SUR","SWE","CHE","SYR","TWN","TJK","TZA","THA","TLS","TGO","TON","TTO","TUN","TUR","TKM","TUV","UGA","UKR","ARE","GBR","USA","URY","UZB","VUT","VAT","VEN","VNM","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":{"description":"Credit or debit card number","type":"string"},"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":{"description":"Card verification value (CVV/CVC)","type":"string"},"cardHolderName":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-zÀ-ÖØ-öø-ÿ'\\- ]+$","description":"Name of the cardholder as it appears on the card"},"cardBrand":{"type":"string","enum":["VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","ELO","MIR","HIPERCARD","HIPER","DANKORT","RUPAY","ELECTRON","UNKNOWN"]},"iin":{"oneOf":[{"type":"string","minLength":6,"maxLength":6},{"type":"string","minLength":8,"maxLength":8}]},"save":{"type":"boolean"}},"required":["cardNumber","expiryMonth","expiryYear","cvv"],"description":"Credit or debit card details"}},"required":["appId","amount","device","txRefId","card"],"description":"Request schema for debiting a card. Note: when routing to the PSP simulator (non-production environments only), card outcomes are driven by the card PAN and/or amount last-2-digits as documented below.","example":{"appId":"towl-test-app","txRefId":"TOWL-42-DENT-DONT-PANIC-001","amount":{"amt":24.42,"cy":"USD"},"device":{"ip":"42.42.42.42"},"card":{"cardNumber":"4242424242424242","expiryMonth":1,"expiryYear":2029,"cvv":"123","cardHolderName":"Authur Dent"},"user":{"userId":"DontPanic42","firstName":"Arthur","middleName":"Urban","lastName":"Dent","email":"arthur.urban@babelfish.io","phone":"+46701234567","address":{"line1":"Handduksvägen 42, lgh 1101","city":"Stockholm","state":"Stockholm","postalCode":"11122","countryCode":"SWE"}},"successUrl":"https://your-domain.com/success?id=${id}&statusCode=${statusCode}","failureUrl":"https://your-domain.com/failed?id=${id}&statusCode=${statusCode}","callbackUrl":"https://your-server.com/webhooks/payment-callback"}}}}},"responses":{"200":{"description":"API response schema for payment","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"txAmount":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"description":"Monetary amount with currency"},"txFee":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"description":"Monetary amount with currency"},"txRefId":{"type":"string","maxLength":255},"state":{"type":"string","enum":["success","processing","waiting","approval","declined","unknown","error","cancelled"],"description":"Payment transaction state"},"statusCode":{"type":"string","enum":["approved","do_not_honor","suspected_fraud","invalid_trx","invalid_amt","invalid_account","invalid_response","no_transaction","restricted_card","insufficient_funds","expired_card","trx_not_permitted","exceeds_limit","exceeds_frequency","invalid_cvv","issuer_err","dest_not_found","psp_malfunction","unable_to_authorize","3ds_auth_failure","psp_limits_reached","psp_timeout","user_aborted_trx","avs_response","no_auth_corresponding","already_captured","already_cancelled","already_refunded","unknown_card","currency_not_supported","amt_over_max","amt_under_min","mobile_block","email_block","ip_block","bin_block","device_block","user_block","account_block","risk_block","duplicate_trx","already_chargedback","too_old_to_refund","no_partial_refund","partial_refund_over","redirect","redirect_timeout","processing","routing_error","system_error","psp_error","bad_request","other"],"description":"Harmonized response codes"},"statusMessage":{"type":"string"},"redirectUrl":{"type":"string","format":"uri"}},"required":["id"],"description":"API response schema for payment","example":{"id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","txAmount":{"amt":23.56,"cy":"USD"},"txRefId":"TOWL-42-DENT-DONT-PANIC-001","state":"success","statusCode":"approved"}}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}}}}},"/api/v1/payment/card/debit":{"post":{"description":"Creates an authorization hold on a card for a specified amount without capturing the funds.\n\n## Test Cards\n\n### Approved (no 3DS)\n| PAN | statusCode | responseCode |\n|-----|------------|--------------|\n| 4242424242424242 | approved | 0 |\n| 4111111111111111 | approved | 0 |\n| 5555555555554444 | approved | 0 |\n| 378282246310005 | approved | 0 |\n\n### Approved (3DS challenge)\n| PAN | statusCode | responseCode |\n|-----|------------|--------------|\n| 4000000000003220 | approved | 0 |\n| 4000002500003155 | approved | 0 |\n| 5200828282828210 | approved | 0 |\n\n### Declined\n| PAN | statusCode | responseCode |\n|-----|------------|--------------|\n| 4000000000000002 | do_not_honor | 5 |\n| 4000000000009995 | insufficient_funds | 51 |\n| 4000000000000069 | expired_card | 54 |\n| 4000000000000127 | invalid_cvv | 79 |\n| 4000000000000119 | psp_malfunction | 96 |\n| 4100000000000019 | suspected_fraud | 59 |\n| 4000000000000259 | issuer_err | 91 |\n| 4000000000000341 | 3ds_auth_failure | 103 |\n| 4000000000000051 | psp_timeout | 105 |","summary":"Debit a card","tags":["payments"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"appId":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[a-z0-9-]+$"},"amount":{"type":"object","properties":{"amt":{"type":"number","minimum":0,"maximum":1000000000,"exclusiveMinimum":0,"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":"Monetary amount with currency"},"device":{"type":"object","properties":{"ip":{"type":"string"},"userAgent":{"type":"string"},"deviceType":{"type":"string","enum":["desktop","mobile","tablet","unknown"]}},"required":["ip"],"description":"Enduser device details"},"user":{"type":"object","properties":{"userId":{"type":"string","minLength":1,"maxLength":100},"firstName":{"type":"string","minLength":1,"maxLength":100},"middleName":{"type":"string","minLength":1,"maxLength":100},"lastName":{"type":"string","minLength":1,"maxLength":100},"email":{"type":"string","format":"email","maxLength":500,"description":"Email"},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$","description":"Phone number in E.164 format"},"dateOfBirth":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Date of birth in YYYY-MM-DD format"},"address":{"type":"object","properties":{"line1":{"type":"string","maxLength":200},"line2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":100},"state":{"type":"string","maxLength":100},"postalCode":{"type":"string","maxLength":20},"countryCode":{"type":"string","enum":["AFG","ALA","ALB","DZA","ASM","AND","AGO","AIA","ATA","ATG","ARG","ARM","ABW","AUS","AUT","AZE","BHS","BHR","BGD","BRB","BLR","BEL","BLZ","BEN","BMU","BTN","BOL","BIH","BWA","BRA","BGR","BFA","BDI","KHM","CMR","CAN","CPV","CAF","TCD","CHL","CHN","COL","COM","COG","COD","CRI","CIV","HRV","CUB","CYP","CZE","DNK","DJI","DMA","DOM","ECU","EGY","SLV","GNQ","ERI","EST","ETH","FJI","FIN","FRA","GAB","GMB","GEO","DEU","GHA","GRC","GRD","GTM","GIN","GNB","GUY","HTI","HND","HKG","HUN","ISL","IND","IDN","IRN","IRQ","IRL","ISR","ITA","JAM","JPN","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","MRT","MUS","MEX","FSM","MDA","MCO","MNG","MNE","MAR","MOZ","MMR","NAM","NRU","NPL","NLD","NZL","NIC","NER","NGA","NOR","OMN","PAK","PLW","PSE","PAN","PNG","PRY","PER","PHL","POL","PRT","QAT","ROU","RUS","RWA","KNA","LCA","VCT","WSM","SMR","STP","SAU","SEN","SRB","SYC","SLE","SGP","SVK","SVN","SLB","SOM","ZAF","SSD","ESP","LKA","SDN","SUR","SWE","CHE","SYR","TWN","TJK","TZA","THA","TLS","TGO","TON","TTO","TUN","TUR","TKM","TUV","UGA","UKR","ARE","GBR","USA","URY","UZB","VUT","VAT","VEN","VNM","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","BIH","BWA","BRA","BGR","BFA","BDI","KHM","CMR","CAN","CPV","CAF","TCD","CHL","CHN","COL","COM","COG","COD","CRI","CIV","HRV","CUB","CYP","CZE","DNK","DJI","DMA","DOM","ECU","EGY","SLV","GNQ","ERI","EST","ETH","FJI","FIN","FRA","GAB","GMB","GEO","DEU","GHA","GRC","GRD","GTM","GIN","GNB","GUY","HTI","HND","HKG","HUN","ISL","IND","IDN","IRN","IRQ","IRL","ISR","ITA","JAM","JPN","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","MRT","MUS","MEX","FSM","MDA","MCO","MNG","MNE","MAR","MOZ","MMR","NAM","NRU","NPL","NLD","NZL","NIC","NER","NGA","NOR","OMN","PAK","PLW","PSE","PAN","PNG","PRY","PER","PHL","POL","PRT","QAT","ROU","RUS","RWA","KNA","LCA","VCT","WSM","SMR","STP","SAU","SEN","SRB","SYC","SLE","SGP","SVK","SVN","SLB","SOM","ZAF","SSD","ESP","LKA","SDN","SUR","SWE","CHE","SYR","TWN","TJK","TZA","THA","TLS","TGO","TON","TTO","TUN","TUR","TKM","TUV","UGA","UKR","ARE","GBR","USA","URY","UZB","VUT","VAT","VEN","VNM","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":{"description":"Credit or debit card number","type":"string"},"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":{"description":"Card verification value (CVV/CVC)","type":"string"},"cardHolderName":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-zÀ-ÖØ-öø-ÿ'\\- ]+$","description":"Name of the cardholder as it appears on the card"},"cardBrand":{"type":"string","enum":["VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","ELO","MIR","HIPERCARD","HIPER","DANKORT","RUPAY","ELECTRON","UNKNOWN"]},"iin":{"oneOf":[{"type":"string","minLength":6,"maxLength":6},{"type":"string","minLength":8,"maxLength":8}]},"save":{"type":"boolean"}},"required":["cardNumber","expiryMonth","expiryYear","cvv"],"description":"Credit or debit card details"}},"required":["appId","amount","device","txRefId","card"],"description":"Request schema for debiting a card. Note: when routing to the PSP simulator (non-production environments only), card outcomes are driven by the card PAN and/or amount last-2-digits as documented below.","example":{"appId":"towl-test-app","txRefId":"TOWL-42-DENT-DONT-PANIC-001","amount":{"amt":24.42,"cy":"USD"},"device":{"ip":"42.42.42.42"},"card":{"cardNumber":"4242424242424242","expiryMonth":1,"expiryYear":2029,"cvv":"123","cardHolderName":"Authur Dent"},"user":{"userId":"DontPanic42","firstName":"Arthur","middleName":"Urban","lastName":"Dent","email":"arthur.urban@babelfish.io","phone":"+46701234567","address":{"line1":"Handduksvägen 42, lgh 1101","city":"Stockholm","state":"Stockholm","postalCode":"11122","countryCode":"SWE"}},"successUrl":"https://your-domain.com/success?id=${id}&statusCode=${statusCode}","failureUrl":"https://your-domain.com/failed?id=${id}&statusCode=${statusCode}","callbackUrl":"https://your-server.com/webhooks/payment-callback"}}}}},"responses":{"200":{"description":"API response schema for payment","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"txAmount":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"description":"Monetary amount with currency"},"txFee":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"description":"Monetary amount with currency"},"txRefId":{"type":"string","maxLength":255},"state":{"type":"string","enum":["success","processing","waiting","approval","declined","unknown","error","cancelled"],"description":"Payment transaction state"},"statusCode":{"type":"string","enum":["approved","do_not_honor","suspected_fraud","invalid_trx","invalid_amt","invalid_account","invalid_response","no_transaction","restricted_card","insufficient_funds","expired_card","trx_not_permitted","exceeds_limit","exceeds_frequency","invalid_cvv","issuer_err","dest_not_found","psp_malfunction","unable_to_authorize","3ds_auth_failure","psp_limits_reached","psp_timeout","user_aborted_trx","avs_response","no_auth_corresponding","already_captured","already_cancelled","already_refunded","unknown_card","currency_not_supported","amt_over_max","amt_under_min","mobile_block","email_block","ip_block","bin_block","device_block","user_block","account_block","risk_block","duplicate_trx","already_chargedback","too_old_to_refund","no_partial_refund","partial_refund_over","redirect","redirect_timeout","processing","routing_error","system_error","psp_error","bad_request","other"],"description":"Harmonized response codes"},"statusMessage":{"type":"string"},"redirectUrl":{"type":"string","format":"uri"}},"required":["id"],"description":"API response schema for payment","example":{"id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","txAmount":{"amt":23.56,"cy":"USD"},"txRefId":"TOWL-42-DENT-DONT-PANIC-001","state":"success","statusCode":"approved"}}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}}}}},"/api/v1/payment/card/credit":{"post":{"description":"Push funds directly to a card (Original Credit Transaction / payout). Card details are supplied by the caller — no prior transaction reference is required. 3DS authentication does not apply to outbound credit flows.\n\n## Test Cards\n\n### Approved\n| PAN | statusCode | responseCode |\n|-----|------------|--------------|\n| 4242424242424242 | approved | 0 |\n| 4111111111111111 | approved | 0 |\n| 5555555555554444 | approved | 0 |\n| 378282246310005 | approved | 0 |\n\n### Declined\n| PAN | statusCode | responseCode |\n|-----|------------|--------------|\n| 4000000000000002 | do_not_honor | 5 |\n| 4000000000009995 | insufficient_funds | 51 |\n| 4000000000000069 | expired_card | 54 |\n| 4000000000000127 | invalid_cvv | 79 |\n| 4000000000000119 | psp_malfunction | 96 |\n| 4100000000000019 | suspected_fraud | 59 |\n| 4000000000000259 | issuer_err | 91 |\n| 4000000000000051 | psp_timeout | 105 |","summary":"Credit a card (OCT / payout)","tags":["payments"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"appId":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[a-z0-9-]+$"},"amount":{"type":"object","properties":{"amt":{"type":"number","minimum":0,"maximum":1000000000,"exclusiveMinimum":0,"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":"Monetary amount with currency"},"device":{"type":"object","properties":{"ip":{"type":"string"},"userAgent":{"type":"string"},"deviceType":{"type":"string","enum":["desktop","mobile","tablet","unknown"]}},"required":["ip"],"description":"Enduser device details"},"user":{"type":"object","properties":{"userId":{"type":"string","minLength":1,"maxLength":100},"firstName":{"type":"string","minLength":1,"maxLength":100},"middleName":{"type":"string","minLength":1,"maxLength":100},"lastName":{"type":"string","minLength":1,"maxLength":100},"email":{"type":"string","format":"email","maxLength":500,"description":"Email"},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$","description":"Phone number in E.164 format"},"dateOfBirth":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Date of birth in YYYY-MM-DD format"},"address":{"type":"object","properties":{"line1":{"type":"string","maxLength":200},"line2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":100},"state":{"type":"string","maxLength":100},"postalCode":{"type":"string","maxLength":20},"countryCode":{"type":"string","enum":["AFG","ALA","ALB","DZA","ASM","AND","AGO","AIA","ATA","ATG","ARG","ARM","ABW","AUS","AUT","AZE","BHS","BHR","BGD","BRB","BLR","BEL","BLZ","BEN","BMU","BTN","BOL","BIH","BWA","BRA","BGR","BFA","BDI","KHM","CMR","CAN","CPV","CAF","TCD","CHL","CHN","COL","COM","COG","COD","CRI","CIV","HRV","CUB","CYP","CZE","DNK","DJI","DMA","DOM","ECU","EGY","SLV","GNQ","ERI","EST","ETH","FJI","FIN","FRA","GAB","GMB","GEO","DEU","GHA","GRC","GRD","GTM","GIN","GNB","GUY","HTI","HND","HKG","HUN","ISL","IND","IDN","IRN","IRQ","IRL","ISR","ITA","JAM","JPN","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","MRT","MUS","MEX","FSM","MDA","MCO","MNG","MNE","MAR","MOZ","MMR","NAM","NRU","NPL","NLD","NZL","NIC","NER","NGA","NOR","OMN","PAK","PLW","PSE","PAN","PNG","PRY","PER","PHL","POL","PRT","QAT","ROU","RUS","RWA","KNA","LCA","VCT","WSM","SMR","STP","SAU","SEN","SRB","SYC","SLE","SGP","SVK","SVN","SLB","SOM","ZAF","SSD","ESP","LKA","SDN","SUR","SWE","CHE","SYR","TWN","TJK","TZA","THA","TLS","TGO","TON","TTO","TUN","TUR","TKM","TUV","UGA","UKR","ARE","GBR","USA","URY","UZB","VUT","VAT","VEN","VNM","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","BIH","BWA","BRA","BGR","BFA","BDI","KHM","CMR","CAN","CPV","CAF","TCD","CHL","CHN","COL","COM","COG","COD","CRI","CIV","HRV","CUB","CYP","CZE","DNK","DJI","DMA","DOM","ECU","EGY","SLV","GNQ","ERI","EST","ETH","FJI","FIN","FRA","GAB","GMB","GEO","DEU","GHA","GRC","GRD","GTM","GIN","GNB","GUY","HTI","HND","HKG","HUN","ISL","IND","IDN","IRN","IRQ","IRL","ISR","ITA","JAM","JPN","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","MRT","MUS","MEX","FSM","MDA","MCO","MNG","MNE","MAR","MOZ","MMR","NAM","NRU","NPL","NLD","NZL","NIC","NER","NGA","NOR","OMN","PAK","PLW","PSE","PAN","PNG","PRY","PER","PHL","POL","PRT","QAT","ROU","RUS","RWA","KNA","LCA","VCT","WSM","SMR","STP","SAU","SEN","SRB","SYC","SLE","SGP","SVK","SVN","SLB","SOM","ZAF","SSD","ESP","LKA","SDN","SUR","SWE","CHE","SYR","TWN","TJK","TZA","THA","TLS","TGO","TON","TTO","TUN","TUR","TKM","TUV","UGA","UKR","ARE","GBR","USA","URY","UZB","VUT","VAT","VEN","VNM","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":{"description":"Credit or debit card number","type":"string"},"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":{"description":"Card verification value (CVV/CVC)","type":"string"},"cardHolderName":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-zÀ-ÖØ-öø-ÿ'\\- ]+$","description":"Name of the cardholder as it appears on the card"},"cardBrand":{"type":"string","enum":["VISA","MASTERCARD","AMEX","DINERS","DISCOVER","JCB","UNIONPAY","MAESTRO","ELO","MIR","HIPERCARD","HIPER","DANKORT","RUPAY","ELECTRON","UNKNOWN"]},"iin":{"oneOf":[{"type":"string","minLength":6,"maxLength":6},{"type":"string","minLength":8,"maxLength":8}]},"save":{"type":"boolean"}},"required":["cardNumber","expiryMonth","expiryYear"],"description":"Credit or debit card details"}},"required":["appId","amount","device","txRefId","card"],"description":"Request schema for crediting (paying out to) a card. No 3DS is required for OCT/payout flows.","example":{"appId":"towl-test-app","txRefId":"TOWL-42-DENT-PAYOUT-001","amount":{"amt":24.42,"cy":"USD"},"device":{"ip":"42.42.42.42"},"card":{"cardNumber":"4242424242424242","expiryMonth":1,"expiryYear":2029,"cvv":"123","cardHolderName":"Authur Dent"},"user":{"userId":"DontPanic42","firstName":"Arthur","middleName":"Urban","lastName":"Dent","email":"arthur.urban@babelfish.io","phone":"+46701234567","address":{"line1":"Handduksvägen 42, lgh 1101","city":"Stockholm","state":"Stockholm","postalCode":"11122","countryCode":"SWE"}},"callbackUrl":"https://your-server.com/webhooks/payment-callback"}}}}},"responses":{"200":{"description":"API response schema for payment","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"txAmount":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"description":"Monetary amount with currency"},"txFee":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"description":"Monetary amount with currency"},"txRefId":{"type":"string","maxLength":255},"state":{"type":"string","enum":["success","processing","waiting","approval","declined","unknown","error","cancelled"],"description":"Payment transaction state"},"statusCode":{"type":"string","enum":["approved","do_not_honor","suspected_fraud","invalid_trx","invalid_amt","invalid_account","invalid_response","no_transaction","restricted_card","insufficient_funds","expired_card","trx_not_permitted","exceeds_limit","exceeds_frequency","invalid_cvv","issuer_err","dest_not_found","psp_malfunction","unable_to_authorize","3ds_auth_failure","psp_limits_reached","psp_timeout","user_aborted_trx","avs_response","no_auth_corresponding","already_captured","already_cancelled","already_refunded","unknown_card","currency_not_supported","amt_over_max","amt_under_min","mobile_block","email_block","ip_block","bin_block","device_block","user_block","account_block","risk_block","duplicate_trx","already_chargedback","too_old_to_refund","no_partial_refund","partial_refund_over","redirect","redirect_timeout","processing","routing_error","system_error","psp_error","bad_request","other"],"description":"Harmonized response codes"},"statusMessage":{"type":"string"},"redirectUrl":{"type":"string","format":"uri"}},"required":["id"],"description":"API response schema for payment","example":{"id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","txAmount":{"amt":23.56,"cy":"USD"},"txRefId":"TOWL-42-DENT-DONT-PANIC-001","state":"success","statusCode":"approved"}}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}}}}},"/api/v1/payment/card/refund":{"post":{"description":"Refunds a previously captured charge.","summary":"Refund a charge","tags":["payments"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"callbackUrl":{"type":"string","format":"uri","description":"URL to receive webhook callback with transaction result"}},"required":["id"],"example":{"id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","callbackUrl":"https://your-server.com/webhooks/payment-callback"}}}}},"responses":{"200":{"description":"API response schema for payment","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"txAmount":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"description":"Monetary amount with currency"},"txFee":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"description":"Monetary amount with currency"},"txRefId":{"type":"string","maxLength":255},"state":{"type":"string","enum":["success","processing","waiting","approval","declined","unknown","error","cancelled"],"description":"Payment transaction state"},"statusCode":{"type":"string","enum":["approved","do_not_honor","suspected_fraud","invalid_trx","invalid_amt","invalid_account","invalid_response","no_transaction","restricted_card","insufficient_funds","expired_card","trx_not_permitted","exceeds_limit","exceeds_frequency","invalid_cvv","issuer_err","dest_not_found","psp_malfunction","unable_to_authorize","3ds_auth_failure","psp_limits_reached","psp_timeout","user_aborted_trx","avs_response","no_auth_corresponding","already_captured","already_cancelled","already_refunded","unknown_card","currency_not_supported","amt_over_max","amt_under_min","mobile_block","email_block","ip_block","bin_block","device_block","user_block","account_block","risk_block","duplicate_trx","already_chargedback","too_old_to_refund","no_partial_refund","partial_refund_over","redirect","redirect_timeout","processing","routing_error","system_error","psp_error","bad_request","other"],"description":"Harmonized response codes"},"statusMessage":{"type":"string"},"redirectUrl":{"type":"string","format":"uri"}},"required":["id"],"description":"API response schema for payment","example":{"id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","txAmount":{"amt":23.56,"cy":"USD"},"txRefId":"TOWL-42-DENT-DONT-PANIC-001","state":"success","statusCode":"approved"}}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}}}}},"/api/v1/payment/card/void":{"post":{"description":"Cancels an authorization hold without capturing.","summary":"Void an authorization","tags":["payments"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"callbackUrl":{"type":"string","format":"uri","description":"URL to receive webhook callback with transaction result"}},"required":["id"],"example":{"id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","callbackUrl":"https://your-server.com/webhooks/payment-callback"}}}}},"responses":{"200":{"description":"API response schema for payment","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"txAmount":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"description":"Monetary amount with currency"},"txFee":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"description":"Monetary amount with currency"},"txRefId":{"type":"string","maxLength":255},"state":{"type":"string","enum":["success","processing","waiting","approval","declined","unknown","error","cancelled"],"description":"Payment transaction state"},"statusCode":{"type":"string","enum":["approved","do_not_honor","suspected_fraud","invalid_trx","invalid_amt","invalid_account","invalid_response","no_transaction","restricted_card","insufficient_funds","expired_card","trx_not_permitted","exceeds_limit","exceeds_frequency","invalid_cvv","issuer_err","dest_not_found","psp_malfunction","unable_to_authorize","3ds_auth_failure","psp_limits_reached","psp_timeout","user_aborted_trx","avs_response","no_auth_corresponding","already_captured","already_cancelled","already_refunded","unknown_card","currency_not_supported","amt_over_max","amt_under_min","mobile_block","email_block","ip_block","bin_block","device_block","user_block","account_block","risk_block","duplicate_trx","already_chargedback","too_old_to_refund","no_partial_refund","partial_refund_over","redirect","redirect_timeout","processing","routing_error","system_error","psp_error","bad_request","other"],"description":"Harmonized response codes"},"statusMessage":{"type":"string"},"redirectUrl":{"type":"string","format":"uri"}},"required":["id"],"description":"API response schema for payment","example":{"id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","txAmount":{"amt":23.56,"cy":"USD"},"txRefId":"TOWL-42-DENT-DONT-PANIC-001","state":"success","statusCode":"approved"}}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}}}}},"/api/v1/payment/card/capture":{"post":{"description":"Captures funds from a previously authorized charge.","summary":"Capture an authorization","tags":["payments"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"callbackUrl":{"type":"string","format":"uri","description":"URL to receive webhook callback with transaction result"}},"required":["id"],"example":{"id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","callbackUrl":"https://your-server.com/webhooks/payment-callback"}}}}},"responses":{"200":{"description":"API response schema for payment","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"txAmount":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"description":"Monetary amount with currency"},"txFee":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"description":"Monetary amount with currency"},"txRefId":{"type":"string","maxLength":255},"state":{"type":"string","enum":["success","processing","waiting","approval","declined","unknown","error","cancelled"],"description":"Payment transaction state"},"statusCode":{"type":"string","enum":["approved","do_not_honor","suspected_fraud","invalid_trx","invalid_amt","invalid_account","invalid_response","no_transaction","restricted_card","insufficient_funds","expired_card","trx_not_permitted","exceeds_limit","exceeds_frequency","invalid_cvv","issuer_err","dest_not_found","psp_malfunction","unable_to_authorize","3ds_auth_failure","psp_limits_reached","psp_timeout","user_aborted_trx","avs_response","no_auth_corresponding","already_captured","already_cancelled","already_refunded","unknown_card","currency_not_supported","amt_over_max","amt_under_min","mobile_block","email_block","ip_block","bin_block","device_block","user_block","account_block","risk_block","duplicate_trx","already_chargedback","too_old_to_refund","no_partial_refund","partial_refund_over","redirect","redirect_timeout","processing","routing_error","system_error","psp_error","bad_request","other"],"description":"Harmonized response codes"},"statusMessage":{"type":"string"},"redirectUrl":{"type":"string","format":"uri"}},"required":["id"],"description":"API response schema for payment","example":{"id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","txAmount":{"amt":23.56,"cy":"USD"},"txRefId":"TOWL-42-DENT-DONT-PANIC-001","state":"success","statusCode":"approved"}}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}}}}},"/api/v1/payment/card/cancel":{"post":{"description":"Cancels a payment transaction.","summary":"Cancel a transaction","tags":["payments"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"callbackUrl":{"type":"string","format":"uri","description":"URL to receive webhook callback with transaction result"}},"required":["id"],"example":{"id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","callbackUrl":"https://your-server.com/webhooks/payment-callback"}}}}},"responses":{"200":{"description":"API response schema for payment","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"txAmount":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"description":"Monetary amount with currency"},"txFee":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"description":"Monetary amount with currency"},"txRefId":{"type":"string","maxLength":255},"state":{"type":"string","enum":["success","processing","waiting","approval","declined","unknown","error","cancelled"],"description":"Payment transaction state"},"statusCode":{"type":"string","enum":["approved","do_not_honor","suspected_fraud","invalid_trx","invalid_amt","invalid_account","invalid_response","no_transaction","restricted_card","insufficient_funds","expired_card","trx_not_permitted","exceeds_limit","exceeds_frequency","invalid_cvv","issuer_err","dest_not_found","psp_malfunction","unable_to_authorize","3ds_auth_failure","psp_limits_reached","psp_timeout","user_aborted_trx","avs_response","no_auth_corresponding","already_captured","already_cancelled","already_refunded","unknown_card","currency_not_supported","amt_over_max","amt_under_min","mobile_block","email_block","ip_block","bin_block","device_block","user_block","account_block","risk_block","duplicate_trx","already_chargedback","too_old_to_refund","no_partial_refund","partial_refund_over","redirect","redirect_timeout","processing","routing_error","system_error","psp_error","bad_request","other"],"description":"Harmonized response codes"},"statusMessage":{"type":"string"},"redirectUrl":{"type":"string","format":"uri"}},"required":["id"],"description":"API response schema for payment","example":{"id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","txAmount":{"amt":23.56,"cy":"USD"},"txRefId":"TOWL-42-DENT-DONT-PANIC-001","state":"success","statusCode":"approved"}}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}}}}},"/api/v1/payment/status/{id}":{"get":{"description":"Get the status of a payment transaction by its ID.","summary":"Get payment status","tags":["payments"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API response schema for payment","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"txAmount":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"description":"Monetary amount with currency"},"txFee":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"description":"Monetary amount with currency"},"txRefId":{"type":"string","maxLength":255},"state":{"type":"string","enum":["success","processing","waiting","approval","declined","unknown","error","cancelled"],"description":"Payment transaction state"},"statusCode":{"type":"string","enum":["approved","do_not_honor","suspected_fraud","invalid_trx","invalid_amt","invalid_account","invalid_response","no_transaction","restricted_card","insufficient_funds","expired_card","trx_not_permitted","exceeds_limit","exceeds_frequency","invalid_cvv","issuer_err","dest_not_found","psp_malfunction","unable_to_authorize","3ds_auth_failure","psp_limits_reached","psp_timeout","user_aborted_trx","avs_response","no_auth_corresponding","already_captured","already_cancelled","already_refunded","unknown_card","currency_not_supported","amt_over_max","amt_under_min","mobile_block","email_block","ip_block","bin_block","device_block","user_block","account_block","risk_block","duplicate_trx","already_chargedback","too_old_to_refund","no_partial_refund","partial_refund_over","redirect","redirect_timeout","processing","routing_error","system_error","psp_error","bad_request","other"],"description":"Harmonized response codes"},"statusMessage":{"type":"string"},"redirectUrl":{"type":"string","format":"uri"}},"required":["id"],"description":"API response schema for payment","example":{"id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","txAmount":{"amt":23.56,"cy":"USD"},"txRefId":"TOWL-42-DENT-DONT-PANIC-001","state":"success","statusCode":"approved"}}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}}}}},"/api/v1/payment/checkout-tokens":{"post":{"description":"Creates a checkout API client token for use with checkout API.","summary":"Create checkout API client token","tags":["payments"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"type":"object","properties":{"appId":{"type":"string","minLength":3,"maxLength":256,"pattern":"^[a-z0-9-]+$","description":"Application slug ID"},"expiresIn":{"default":300,"type":"integer","minimum":60,"maximum":3600,"description":"Token expiry in seconds (default 5 minutes)"},"allowedOrigins":{"type":"array","items":{"type":"string"},"maxItems":10,"description":"List of allowed origins for CORS and Origin header enforcement. The browser SDK must send requests from one of these origins."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Optional metadata"},"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","format":"email","maxLength":500,"description":"Email"},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$","description":"Phone number in E.164 format"},"dateOfBirth":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Date of birth in YYYY-MM-DD format"},"address":{"type":"object","properties":{"line1":{"type":"string","maxLength":200},"line2":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":100},"state":{"type":"string","maxLength":100},"postalCode":{"type":"string","maxLength":20},"countryCode":{"type":"string","enum":["AFG","ALA","ALB","DZA","ASM","AND","AGO","AIA","ATA","ATG","ARG","ARM","ABW","AUS","AUT","AZE","BHS","BHR","BGD","BRB","BLR","BEL","BLZ","BEN","BMU","BTN","BOL","BIH","BWA","BRA","BGR","BFA","BDI","KHM","CMR","CAN","CPV","CAF","TCD","CHL","CHN","COL","COM","COG","COD","CRI","CIV","HRV","CUB","CYP","CZE","DNK","DJI","DMA","DOM","ECU","EGY","SLV","GNQ","ERI","EST","ETH","FJI","FIN","FRA","GAB","GMB","GEO","DEU","GHA","GRC","GRD","GTM","GIN","GNB","GUY","HTI","HND","HKG","HUN","ISL","IND","IDN","IRN","IRQ","IRL","ISR","ITA","JAM","JPN","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","MRT","MUS","MEX","FSM","MDA","MCO","MNG","MNE","MAR","MOZ","MMR","NAM","NRU","NPL","NLD","NZL","NIC","NER","NGA","NOR","OMN","PAK","PLW","PSE","PAN","PNG","PRY","PER","PHL","POL","PRT","QAT","ROU","RUS","RWA","KNA","LCA","VCT","WSM","SMR","STP","SAU","SEN","SRB","SYC","SLE","SGP","SVK","SVN","SLB","SOM","ZAF","SSD","ESP","LKA","SDN","SUR","SWE","CHE","SYR","TWN","TJK","TZA","THA","TLS","TGO","TON","TTO","TUN","TUR","TKM","TUV","UGA","UKR","ARE","GBR","USA","URY","UZB","VUT","VAT","VEN","VNM","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","BIH","BWA","BRA","BGR","BFA","BDI","KHM","CMR","CAN","CPV","CAF","TCD","CHL","CHN","COL","COM","COG","COD","CRI","CIV","HRV","CUB","CYP","CZE","DNK","DJI","DMA","DOM","ECU","EGY","SLV","GNQ","ERI","EST","ETH","FJI","FIN","FRA","GAB","GMB","GEO","DEU","GHA","GRC","GRD","GTM","GIN","GNB","GUY","HTI","HND","HKG","HUN","ISL","IND","IDN","IRN","IRQ","IRL","ISR","ITA","JAM","JPN","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","MRT","MUS","MEX","FSM","MDA","MCO","MNG","MNE","MAR","MOZ","MMR","NAM","NRU","NPL","NLD","NZL","NIC","NER","NGA","NOR","OMN","PAK","PLW","PSE","PAN","PNG","PRY","PER","PHL","POL","PRT","QAT","ROU","RUS","RWA","KNA","LCA","VCT","WSM","SMR","STP","SAU","SEN","SRB","SYC","SLE","SGP","SVK","SVN","SLB","SOM","ZAF","SSD","ESP","LKA","SDN","SUR","SWE","CHE","SYR","TWN","TJK","TZA","THA","TLS","TGO","TON","TTO","TUN","TUR","TKM","TUV","UGA","UKR","ARE","GBR","USA","URY","UZB","VUT","VAT","VEN","VNM","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":{"type":"boolean","description":"If true, the response includes a fully-qualified checkout URL that can be used to redirect or embed the hosted checkout."},"amount":{"type":"object","properties":{"amt":{"type":"number","minimum":0,"maximum":1000000000,"exclusiveMinimum":0,"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":"Payment amount. When set, the amount is locked into the session and cannot be changed on the client side."},"embedMode":{"type":"string","enum":["redirect","iframe"],"description":"Embedding mode for the hosted checkout. Included in the checkout URL when checkoutUrl is true."},"parentOrigin":{"type":"string","description":"Origin of the merchant page embedding the checkout (iframe). Included in the checkout URL when checkoutUrl is true."}},"required":["appId","allowedOrigins","user"],"description":"Request schema for creating a checkout token","example":{"appId":"towl-test-app","expiresIn":300,"allowedOrigins":["https://your-domain.com"],"user":{"userId":"DontPanic42","firstName":"Arthur","middleName":"Urban","lastName":"Dent","email":"arthur.urban@babelfish.io","phone":"+46701234567","address":{"line1":"Handduksvägen 42, lgh 1101","city":"Stockholm","state":"Stockholm","postalCode":"11122","countryCode":"SWE"}},"successUrl":"https://your-domain.com/success?id=${id}&statusCode=${statusCode}","failureUrl":"https://your-domain.com/failed?id=${id}&statusCode=${statusCode}","callbackUrl":"https://your-server.com/webhooks/payment-callback","checkoutUrl":true,"amount":{"amt":100,"cy":"EUR"},"embedMode":"iframe","parentOrigin":"https://your-domain.com"}}}}},"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":{"type":"string","format":"uri","description":"Fully-qualified hosted checkout URL. Only present when the request set checkoutUrl=true."}},"required":["token","expiresAt","allowedOrigins"],"description":"Response schema for checkout token creation"}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}}}}},"/api/v1/checkout/options":{"get":{"description":"Returns a list of available payment options with their required fields.","summary":"List available payment options","tags":["checkout"],"parameters":[],"responses":{"200":{"description":"200","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["card-debit-new","card-debit-token","card-credit-token","open-banking-debit"],"description":"Payment option type identifier"},"fields":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Field name"},"type":{"type":"string","enum":["string","number","boolean"],"description":"Field type"},"required":{"type":"boolean","description":"Whether the field is required"},"label":{"type":"string","description":"Display label for the field"},"placeholder":{"type":"string","description":"Placeholder text"},"regex":{"type":"string","description":"Validation regex pattern"}},"required":["name","type","required","label"],"description":"Schema for a payment option field"},"description":"Fields required for this payment option"},"icon":{"type":"string","description":"Icon URL or name"}},"required":["type","fields"],"description":"Schema for a payment option","example":{"type":"card-debit-new","fields":[{"name":"encCardNumber","type":"string","required":true,"label":"Encrypted card number"},{"name":"encCvv","type":"string","required":true,"label":"Encrypted CVV"},{"name":"expiryMonth","type":"number","required":true,"label":"Card expiry month (1-12)","regex":"^(1[0-2]|[1-9])$"},{"name":"expiryYear","type":"number","required":true,"label":"Card expiry year (4 digits)","regex":"^(202[6-9]|20[3-9]\\d|2100)$"},{"name":"cardholderName","type":"string","required":false,"label":"Name of the cardholder as it appears on the card","regex":"^[A-Za-zÀ-ÖØ-öø-ÿ'\\- ]+$"}]}},"example":[{"type":"card-debit-new","fields":[{"name":"encCardNumber","type":"string","required":true,"label":"Encrypted card number"},{"name":"encCvv","type":"string","required":true,"label":"Encrypted CVV"},{"name":"expiryMonth","type":"number","required":true,"label":"Card expiry month (1-12)","regex":"^(1[0-2]|[1-9])$"},{"name":"expiryYear","type":"number","required":true,"label":"Card expiry year (4 digits)","regex":"^(202[6-9]|20[3-9]\\d|2100)$"},{"name":"cardholderName","type":"string","required":false,"label":"Name of the cardholder as it appears on the card","regex":"^[A-Za-zÀ-ÖØ-öø-ÿ'\\- ]+$"}]},{"type":"card-debit-token","fields":[{"name":"tokenId","type":"string","required":true,"label":"Encrypted card number"},{"name":"encCvv","type":"string","required":true,"label":"Encrypted CVV"},{"name":"expiryMonth","type":"number","required":false,"label":"Card expiry month (1-12)","regex":"^(1[0-2]|[1-9])$"},{"name":"expiryYear","type":"number","required":false,"label":"Card expiry year (4 digits)","regex":"^(202[6-9]|20[3-9]\\d|2100)$"}]},{"type":"card-credit-token","fields":[{"name":"encCardNumber","type":"string","required":true,"label":"Encrypted card number"},{"name":"encCvv","type":"string","required":true,"label":"Encrypted CVV"},{"name":"expiryMonth","type":"number","required":false,"label":"Card expiry month (1-12)","regex":"^(1[0-2]|[1-9])$"},{"name":"expiryYear","type":"number","required":false,"label":"Card expiry year (4 digits)","regex":"^(202[6-9]|20[3-9]\\d|2100)$"}]},{"type":"open-banking-debit","fields":[]}]}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}}}}},"/api/v1/checkout/debit":{"post":{"description":"Processes a debit payment using the checkout API.","summary":"Process debit payment","tags":["checkout"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"discriminator":{"propertyName":"paymentType"},"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":{"type":"string","maxLength":255,"description":"External transaction reference ID"},"paymentType":{"type":"string","enum":["card-debit-new"]},"encCardNumber":{"type":"string","minLength":1,"maxLength":256,"description":"Encrypted card number"},"encCvv":{"type":"string","minLength":1,"maxLength":256,"description":"Encrypted CVV"},"expiryMonth":{"type":"integer","minimum":1,"maximum":12,"description":"Card expiry month (1-12)"},"expiryYear":{"type":"integer","minimum":1970,"maximum":2100,"description":"Card expiry year (4 digits)"},"cardholderName":{"type":"string","minLength":1,"maxLength":100,"pattern":"^[A-Za-zÀ-ÖØ-öø-ÿ'\\- ]+$","description":"Name of the cardholder as it appears on the card"},"save":{"type":"boolean","description":"Save card for future payments"}},"required":["amount","paymentType","encCardNumber","encCvv","expiryMonth","expiryYear","cardholderName"],"description":"Checkout payload for a new card debit","example":{"paymentType":"card-debit-new","amount":{"amt":24.42,"cy":"USD"},"encCardNumber":"ev:tok:QpEAxV4Ag7P1WtXM4FXQKQ:BQIDBA","encCvv":"ev:tok:FpYAxV4Ag7P1WtXM4ABCDE:XYZ123","expiryMonth":1,"expiryYear":2029,"cardholderName":"Arthur Dent","save":false}},{"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":{"type":"string","maxLength":255,"description":"External transaction reference ID"},"paymentType":{"type":"string","enum":["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","example":{"paymentType":"card-debit-token","amount":{"amt":99,"cy":"EUR"},"tokenId":"ev:tok:QpEAxV4Ag7P1WtXM4FXQKQ:BQIDBA","encCvv":"ev:tok:FpYAxV4Ag7P1WtXM4ABCDE:XYZ123"}},{"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":{"type":"string","maxLength":255,"description":"External transaction reference ID"},"paymentType":{"type":"string","enum":["open-banking-debit"]}},"required":["amount","paymentType"],"description":"Checkout payload for an open banking debit","example":{"paymentType":"open-banking-debit","amount":{"amt":150,"cy":"SEK"}}}],"description":"Request schema for checkout debit","examples":[{"paymentType":"card-debit-new","amount":{"amt":24.42,"cy":"USD"},"encCardNumber":"ev:tok:QpEAxV4Ag7P1WtXM4FXQKQ:BQIDBA","encCvv":"ev:tok:FpYAxV4Ag7P1WtXM4ABCDE:XYZ123","expiryMonth":1,"expiryYear":2029,"cardholderName":"Arthur Dent"},{"paymentType":"card-debit-token","amount":{"amt":99,"cy":"EUR"},"tokenId":"ev:tok:QpEAxV4Ag7P1WtXM4FXQKQ:BQIDBA","encCvv":"ev:tok:FpYAxV4Ag7P1WtXM4ABCDE:XYZ123"},{"paymentType":"open-banking-debit","amount":{"amt":150,"cy":"SEK"}}]}}}},"responses":{"200":{"description":"API response schema for payment","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"txAmount":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"description":"Monetary amount with currency"},"txRefId":{"type":"string","maxLength":255},"state":{"type":"string","enum":["success","processing","waiting","approval","declined","unknown","error","cancelled"],"description":"Payment transaction state"},"statusCode":{"type":"string","enum":["approved","do_not_honor","suspected_fraud","invalid_trx","invalid_amt","invalid_account","invalid_response","no_transaction","restricted_card","insufficient_funds","expired_card","trx_not_permitted","exceeds_limit","exceeds_frequency","invalid_cvv","issuer_err","dest_not_found","psp_malfunction","unable_to_authorize","3ds_auth_failure","psp_limits_reached","psp_timeout","user_aborted_trx","avs_response","no_auth_corresponding","already_captured","already_cancelled","already_refunded","unknown_card","currency_not_supported","amt_over_max","amt_under_min","mobile_block","email_block","ip_block","bin_block","device_block","user_block","account_block","risk_block","duplicate_trx","already_chargedback","too_old_to_refund","no_partial_refund","partial_refund_over","redirect","redirect_timeout","processing","routing_error","system_error","psp_error","bad_request","other"],"description":"Harmonized response codes"},"redirectUrl":{"type":"string","format":"uri"}},"required":["id"],"description":"API response schema for payment"}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}}}}},"/api/v1/checkout/credit":{"post":{"description":"Processes a credit payment using the checkout API.","summary":"Process credit payment","tags":["checkout"],"parameters":[],"requestBody":{"description":"Body","content":{"application/json":{"schema":{"discriminator":{"propertyName":"paymentType"},"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":{"type":"string","maxLength":255,"description":"External transaction reference ID"},"paymentType":{"type":"string","enum":["card-credit-token"]},"encCardNumber":{"type":"string","minLength":1,"maxLength":256,"description":"Encrypted card number"}},"required":["amount","paymentType","encCardNumber"],"description":"Checkout payload for a tokenized card credit","example":{"paymentType":"card-credit-token","amount":{"amt":50,"cy":"EUR"},"encCardNumber":"ev:tok:QpEAxV4Ag7P1WtXM4FXQKQ:BQIDBA"}}],"description":"Request schema for checkout credit","examples":[{"paymentType":"card-credit-token","amount":{"amt":50,"cy":"EUR"},"encCardNumber":"ev:tok:QpEAxV4Ag7P1WtXM4FXQKQ:BQIDBA","encCvv":"ev:tok:FpYAxV4Ag7P1WtXM4ABCDE:XYZ123","expiryMonth":6,"expiryYear":2028}]}}}},"responses":{"200":{"description":"API response schema for payment","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"txAmount":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"description":"Monetary amount with currency"},"txRefId":{"type":"string","maxLength":255},"state":{"type":"string","enum":["success","processing","waiting","approval","declined","unknown","error","cancelled"],"description":"Payment transaction state"},"statusCode":{"type":"string","enum":["approved","do_not_honor","suspected_fraud","invalid_trx","invalid_amt","invalid_account","invalid_response","no_transaction","restricted_card","insufficient_funds","expired_card","trx_not_permitted","exceeds_limit","exceeds_frequency","invalid_cvv","issuer_err","dest_not_found","psp_malfunction","unable_to_authorize","3ds_auth_failure","psp_limits_reached","psp_timeout","user_aborted_trx","avs_response","no_auth_corresponding","already_captured","already_cancelled","already_refunded","unknown_card","currency_not_supported","amt_over_max","amt_under_min","mobile_block","email_block","ip_block","bin_block","device_block","user_block","account_block","risk_block","duplicate_trx","already_chargedback","too_old_to_refund","no_partial_refund","partial_refund_over","redirect","redirect_timeout","processing","routing_error","system_error","psp_error","bad_request","other"],"description":"Harmonized response codes"},"redirectUrl":{"type":"string","format":"uri"}},"required":["id"],"description":"API response schema for payment"}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}}}}},"/api/v1/checkout/status/{id}":{"get":{"description":"Get the status of a checkout payment transaction by its ID.","summary":"Get payment status","tags":["checkout"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"API response schema for payment","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"txAmount":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"description":"Monetary amount with currency"},"txRefId":{"type":"string","maxLength":255},"state":{"type":"string","enum":["success","processing","waiting","approval","declined","unknown","error","cancelled"],"description":"Payment transaction state"},"statusCode":{"type":"string","enum":["approved","do_not_honor","suspected_fraud","invalid_trx","invalid_amt","invalid_account","invalid_response","no_transaction","restricted_card","insufficient_funds","expired_card","trx_not_permitted","exceeds_limit","exceeds_frequency","invalid_cvv","issuer_err","dest_not_found","psp_malfunction","unable_to_authorize","3ds_auth_failure","psp_limits_reached","psp_timeout","user_aborted_trx","avs_response","no_auth_corresponding","already_captured","already_cancelled","already_refunded","unknown_card","currency_not_supported","amt_over_max","amt_under_min","mobile_block","email_block","ip_block","bin_block","device_block","user_block","account_block","risk_block","duplicate_trx","already_chargedback","too_old_to_refund","no_partial_refund","partial_refund_over","redirect","redirect_timeout","processing","routing_error","system_error","psp_error","bad_request","other"],"description":"Harmonized response codes"},"redirectUrl":{"type":"string","format":"uri"}},"required":["id"],"description":"API response schema for payment"}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}}}}},"/api/v1/checkout/revoke/{tokenId}":{"delete":{"description":"Marks a saved card as revoked and removes encrypted data.","summary":"Revoke a saved card","tags":["checkout"],"parameters":[{"name":"tokenId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Response schema for checkout revoke","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"Whether the revocation was successful"}},"required":["success"],"description":"Response schema for checkout revoke"}}}},"400":{"description":"400","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"401":{"description":"401","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"403":{"description":"403","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"404":{"description":"404","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}},"500":{"description":"500","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["message"]}}}}}}}},"info":{"title":"API – Payment","version":"1.0.0"},"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":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"txAmount":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"description":"Monetary amount with currency"},"txFee":{"type":"object","properties":{"amt":{"type":"number","minimum":-1000000000,"maximum":1000000000,"description":"Amount"},"cy":{"type":"string","enum":["USD","EUR","GBP","JPY","CHF","CAD","AUD","SEK","NOK","DKK","PLN","CZK","HUF","RUB","CNY","INR","KRW","SGD","HKD","NZD","MXN","BRL","ZAR","TRY","ILS","THB","MYR","IDR","PHP","VND","JOD","KWD","BHD","OMR","TND","LYD","CLP","COP","PEN","ARS","UYU","EGP","MAD","NGN","KES","GHS","BWP","ZMW","UGX","TZS","ETB","RWF","MUR","SCR","BTC","ETH","LTC","BCH","XRP","ADA","DOT","LINK","XLM","DOGE","BNB","SOL","MATIC","AVAX","ATOM","ALGO","TRX","USDT","USDC","DAI"]}},"required":["amt","cy"],"description":"Monetary amount with currency"},"txRefId":{"type":"string","maxLength":255},"state":{"type":"string","enum":["success","processing","waiting","approval","declined","unknown","error","cancelled"],"description":"Payment transaction state"},"statusCode":{"type":"string","enum":["approved","do_not_honor","suspected_fraud","invalid_trx","invalid_amt","invalid_account","invalid_response","no_transaction","restricted_card","insufficient_funds","expired_card","trx_not_permitted","exceeds_limit","exceeds_frequency","invalid_cvv","issuer_err","dest_not_found","psp_malfunction","unable_to_authorize","3ds_auth_failure","psp_limits_reached","psp_timeout","user_aborted_trx","avs_response","no_auth_corresponding","already_captured","already_cancelled","already_refunded","unknown_card","currency_not_supported","amt_over_max","amt_under_min","mobile_block","email_block","ip_block","bin_block","device_block","user_block","account_block","risk_block","duplicate_trx","already_chargedback","too_old_to_refund","no_partial_refund","partial_refund_over","redirect","redirect_timeout","processing","routing_error","system_error","psp_error","bad_request","other"],"description":"Harmonized response codes"},"statusMessage":{"type":"string"},"redirectUrl":{"type":"string","format":"uri"}},"required":["id"],"description":"Webhook callback payload sent to the customer callbackUrl","example":{"id":"f47ac10b-58cc-4372-a567-0e02b2c3d479","txAmount":{"amt":23.56,"cy":"EUR"},"txRefId":"TOWL-42-DENT-DONT-PANIC-001","state":"success","statusCode":"approved","statusMessage":"Transaction approved"}}}}},"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."}}}}}}