{"openapi":"3.1.0","info":{"title":"Umbra API","description":"Zentec payment API. Every call needs mutual TLS plus an `Authorization: Bearer` token from the Zentec IdP, bound to the client certificate.","version":"v1"},"servers":[{"url":"http://docs.umbra.zenteclabs.dev","description":"Generated server url"}],"security":[{"bearer":[]}],"paths":{"/v1/reversals":{"post":{"tags":["Reversals"],"summary":"Reverse an operation by its reference","description":"For a sale, capture or authorization whose result the client does not know or could not complete. Idempotent, also with Umbra's automatic reversal. Answers with the original operation and its `reversal`.","operationId":"reverse","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReversalRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiResponseObject"}}}}}}},"/v1/payments":{"post":{"tags":["Payments"],"summary":"Create a sale","description":"200 with the result (approved, declined or failed); 202 `pending` when the processor did not answer in time — query by reference. Repeating a reference returns the original answer.","operationId":"create","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiResponsePaymentView"}}}}}}},"/v1/payments/{paymentId}/refunds":{"post":{"tags":["Payments"],"summary":"Refund a payment","description":"From the UTC day after the payment until `refundableUntil`; partial refunds up to the payment's amount.","operationId":"refund","parameters":[{"name":"paymentId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardOperationRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiResponseRefundView"}}}}}}},"/v1/payments/{paymentId}/cancel":{"post":{"tags":["Payments"],"summary":"Cancel a payment","description":"The whole payment, same UTC day, until `cancellableUntil`. Answers with the payment and its `cancellation`.","operationId":"cancel","parameters":[{"name":"paymentId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferenceRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiResponsePaymentView"}}}}}}},"/v1/authorizations":{"post":{"tags":["Authorizations"],"summary":"Pre-authorize an amount","description":"Holds the amount until captured, released or `expiresAt`.","operationId":"create_1","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthorizationRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiResponseAuthorizationView"}}}}}}},"/v1/authorizations/{authorizationId}/release":{"post":{"tags":["Authorizations"],"summary":"Release an authorization","description":"Frees the held amount of an authorization never captured.","operationId":"release","parameters":[{"name":"authorizationId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReferenceRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiResponseAuthorizationView"}}}}}}},"/v1/authorizations/{authorizationId}/capture":{"post":{"tags":["Authorizations"],"summary":"Capture an authorization","description":"Once, up to the authorized amount, with the card. Creates a payment; answers with the authorization and its `capture`.","operationId":"capture","parameters":[{"name":"authorizationId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CardOperationRequest"}}},"required":true},"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiResponseAuthorizationView"}}}}}}},"/v1/payments/{paymentId}":{"get":{"tags":["Payments"],"summary":"Get a payment by id","operationId":"get","parameters":[{"name":"paymentId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiResponsePaymentView"}}}}}}},"/v1/payments/by-reference/{reference}":{"get":{"tags":["Payments"],"summary":"Get a payment by the client's reference","description":"404 means the reference never reached Umbra.","operationId":"getByReference","parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiResponsePaymentView"}}}}}}},"/v1/authorizations/{authorizationId}":{"get":{"tags":["Authorizations"],"summary":"Get an authorization by id","operationId":"get_1","parameters":[{"name":"authorizationId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiResponseAuthorizationView"}}}}}}},"/v1/authorizations/by-reference/{reference}":{"get":{"tags":["Authorizations"],"summary":"Get an authorization by the client's reference","operationId":"getByReference_1","parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiResponseAuthorizationView"}}}}}}},"/error":{"get":{"tags":["api-error-controller"],"operationId":"error","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}},"put":{"tags":["api-error-controller"],"operationId":"error_2","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}},"post":{"tags":["api-error-controller"],"operationId":"error_1","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}},"delete":{"tags":["api-error-controller"],"operationId":"error_3","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}},"options":{"tags":["api-error-controller"],"operationId":"error_6","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}},"head":{"tags":["api-error-controller"],"operationId":"error_5","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}},"patch":{"tags":["api-error-controller"],"operationId":"error_4","responses":{"200":{"description":"OK","content":{"*/*":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}}}}},"components":{"schemas":{"ReversalRequest":{"type":"object","properties":{"reference":{"type":["string","null"],"description":"The reference of the operation to reverse","example":"ord-7Q2K9-0001","pattern":"^[A-Za-z0-9._-]{1,64}$"},"reason":{"type":["string","null"],"pattern":"^(timeout|device_failure|emv_failed|explicit)$"}},"required":["reason","reference"]},"ApiResponseObject":{"type":"object","properties":{"data":{},"meta":{"$ref":"#/components/schemas/Meta"}}},"Meta":{"type":"object","properties":{"traceId":{"type":"string"}}},"CardInput":{"type":"object","properties":{"entryMode":{"type":["string","null"],"enum":["chip","contactless_chip","swipe","contactless_swipe","fallback","manual"]},"track2":{"type":["string","null"]},"emv":{"type":["string","null"],"description":"TLV hex as the EMV kernel returns it"},"pan":{"type":["string","null"]},"expiry":{"type":["string","null"],"description":"YYMM"},"cvv":{"type":["string","null"]}}},"Contactless":{"type":"object","properties":{"fastPayment":{"type":"boolean"}}},"Installments":{"type":"object","properties":{"count":{"type":["integer","null"],"format":"int32","maximum":48,"minimum":2},"plan":{"type":["string","null"],"pattern":"^no_interest$"}},"required":["count","plan"]},"PaymentRequest":{"type":"object","properties":{"reference":{"type":["string","null"],"example":"ord-7Q2K9-0001","pattern":"^[A-Za-z0-9._-]{1,64}$"},"deviceId":{"type":["string","null"],"example":"4795B69708C51ACC9B11","pattern":"^[A-Za-z0-9]{1,40}$"},"merchantId":{"type":["string","null"],"pattern":"^mer_[0-9A-Za-z]{26}$"},"amount":{"type":["integer","null"],"format":"int64","description":"Total in minor units (cents), tip included","example":10200,"exclusiveMinimum":0,"maximum":999999999999},"currency":{"type":["string","null"],"pattern":"^MXN$"},"tip":{"type":["integer","null"],"format":"int64","description":"Informative: how much of the total is tip","example":1000,"minimum":0},"installments":{"oneOf":[{"$ref":"#/components/schemas/Installments"},{"type":"null"}]},"card":{"oneOf":[{"$ref":"#/components/schemas/CardInput"},{"type":"null"}]},"contactless":{"oneOf":[{"$ref":"#/components/schemas/Contactless"},{"type":"null"}]}},"required":["amount","card","currency","deviceId","reference"]},"ApiResponsePaymentView":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PaymentView"},"meta":{"$ref":"#/components/schemas/Meta"}}},"CancellationView":{"type":"object","properties":{"id":{"type":"string"},"reference":{"type":"string"},"status":{"type":"string"},"result":{"oneOf":[{"$ref":"#/components/schemas/ResultView"},{"type":"null"}]},"authorizationCode":{"type":["string","null"]},"createdAt":{"type":"string","format":"date-time"}}},"PaymentView":{"type":"object","properties":{"id":{"type":"string"},"reference":{"type":"string"},"status":{"type":"string"},"result":{"oneOf":[{"$ref":"#/components/schemas/ResultView"},{"type":"null"}]},"authorizationCode":{"type":["string","null"]},"amount":{"type":"integer","format":"int64"},"approvedAmount":{"type":["integer","null"],"format":"int64"},"currency":{"type":"string"},"cancellableUntil":{"type":["string","null"],"format":"date-time"},"refundableUntil":{"type":["string","null"],"format":"date-time"},"cancellation":{"oneOf":[{"$ref":"#/components/schemas/CancellationView"},{"type":"null"}]},"refundedAmount":{"type":["integer","null"],"format":"int64"},"refunds":{"type":["array","null"],"items":{"$ref":"#/components/schemas/RefundView"}},"reversal":{"oneOf":[{"$ref":"#/components/schemas/ReversalView"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"}}},"RefundView":{"type":"object","properties":{"id":{"type":"string"},"reference":{"type":"string"},"paymentId":{"type":"string"},"status":{"type":"string"},"result":{"oneOf":[{"$ref":"#/components/schemas/ResultView"},{"type":"null"}]},"amount":{"type":"integer","format":"int64"},"approvedAmount":{"type":["integer","null"],"format":"int64"},"createdAt":{"type":"string","format":"date-time"}}},"ResultView":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"}}},"ReversalView":{"type":"object","properties":{"status":{"type":"string"},"result":{"oneOf":[{"$ref":"#/components/schemas/ResultView"},{"type":"null"}]},"reason":{"type":"string"},"createdAt":{"type":"string","format":"date-time"}}},"CardOperationRequest":{"type":"object","properties":{"reference":{"type":["string","null"],"pattern":"^[A-Za-z0-9._-]{1,64}$"},"amount":{"type":["integer","null"],"format":"int64","exclusiveMinimum":0,"maximum":999999999999},"deviceId":{"type":["string","null"],"pattern":"^[A-Za-z0-9]{1,40}$"},"card":{"oneOf":[{"$ref":"#/components/schemas/CardInput"},{"type":"null"}]}},"required":["amount","card","deviceId","reference"]},"ApiResponseRefundView":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/RefundView"},"meta":{"$ref":"#/components/schemas/Meta"}}},"ReferenceRequest":{"type":"object","properties":{"reference":{"type":["string","null"],"example":"cnl-7Q2K9-0001","pattern":"^[A-Za-z0-9._-]{1,64}$"}},"required":["reference"]},"AuthorizationRequest":{"type":"object","properties":{"reference":{"type":["string","null"],"example":"aut-7Q2K9-0001","pattern":"^[A-Za-z0-9._-]{1,64}$"},"deviceId":{"type":["string","null"],"pattern":"^[A-Za-z0-9]{1,40}$"},"merchantId":{"type":["string","null"],"pattern":"^mer_[0-9A-Za-z]{26}$"},"amount":{"type":["integer","null"],"format":"int64","exclusiveMinimum":0,"maximum":999999999999},"currency":{"type":["string","null"],"pattern":"^MXN$"},"card":{"oneOf":[{"$ref":"#/components/schemas/CardInput"},{"type":"null"}]},"contactless":{"oneOf":[{"$ref":"#/components/schemas/Contactless"},{"type":"null"}]}},"required":["amount","card","currency","deviceId","reference"]},"ApiResponseAuthorizationView":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/AuthorizationView"},"meta":{"$ref":"#/components/schemas/Meta"}}},"AuthorizationView":{"type":"object","properties":{"id":{"type":"string"},"reference":{"type":"string"},"status":{"type":"string"},"result":{"oneOf":[{"$ref":"#/components/schemas/ResultView"},{"type":"null"}]},"authorizationCode":{"type":["string","null"]},"amount":{"type":"integer","format":"int64"},"approvedAmount":{"type":["integer","null"],"format":"int64"},"currency":{"type":"string"},"expiresAt":{"type":["string","null"],"format":"date-time"},"capture":{"oneOf":[{"$ref":"#/components/schemas/CaptureView"},{"type":"null"}]},"release":{"oneOf":[{"$ref":"#/components/schemas/ReleaseView"},{"type":"null"}]},"reversal":{"oneOf":[{"$ref":"#/components/schemas/ReversalView"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"}}},"CaptureView":{"type":"object","properties":{"paymentId":{"type":"string"},"reference":{"type":"string"},"status":{"type":"string"},"result":{"oneOf":[{"$ref":"#/components/schemas/ResultView"},{"type":"null"}]},"authorizationCode":{"type":["string","null"]},"amount":{"type":"integer","format":"int64"},"createdAt":{"type":"string","format":"date-time"}}},"ReleaseView":{"type":"object","properties":{"reference":{"type":"string"},"status":{"type":"string"},"result":{"oneOf":[{"$ref":"#/components/schemas/ResultView"},{"type":"null"}]},"createdAt":{"type":"string","format":"date-time"}}},"ApiErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/Body"}}},"Body":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":["object","null"],"additionalProperties":{"type":"string"}},"traceId":{"type":"string"}}}},"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}}}