Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/PloutusLab/krafta-web/llms.txt

Use this file to discover all available pages before exploring further.

The Payments API handles the full receipt-based payment flow used by Krafta. Customers submit a bank transfer or Pago Móvil receipt tied to an existing order; admins then confirm or reject each submission. Active PaymentAccount records are exposed to the checkout UI so customers always see up-to-date bank details.

​
POST /api/payments

Submit a payment receipt for an existing order. The endpoint creates a PaymentSubmission record, sets the order’s status to REPORTED, and returns the new submission’s ID. No authentication is required — any client may submit a receipt as long as they hold a valid orderId.

​
Request body

​
orderId
string
required
The UUID of the order being paid. Must match an existing Order record.
​
method
string
required
Payment method used. Accepted values: "PAGO_MOVIL" or "TRANSFERENCIA".
​
amountReported
number
required
The amount the customer reports having sent, in bolívares (Bs.). Stored as amountReported on the PaymentSubmission; the order’s total is used separately as amountExpected.
​
reference
string
required
The bank reference or transaction confirmation number issued by the sending institution.
​
originBank
string
required
Name of the customer’s sending bank (e.g., "Banesco", "Mercantil").
​
payerName
string
required
Full legal name of the account holder who made the transfer.
​
receiptUrl
string
required
URL of the uploaded receipt image. Use the Upload API to obtain this value before calling this endpoint.

​
Response

{
  "success": true,
  "submissionId": "a3f2c1d4-87b6-4e2a-9c01-f5d3e2a1b098"
}
​
success
boolean
Always true on a successful submission.
​
submissionId
string
UUID of the newly created PaymentSubmission. Store this value if you need to reference the submission in admin verification calls.

​
Side effects

  • The matching Order record’s status is updated to REPORTED.
  • A new PaymentSubmission row is created with status: "REPORTED" and reportedAt set to the current timestamp.

​
Error responses

StatusCondition
400orderId or reference missing from the request body.
500Unexpected server error.

​
PUT /api/payments ADMIN

Verify or reject a previously submitted payment receipt. Requires the ADMIN role. When confirmed, the order moves to CONFIRMED and the payment record is marked verified. When rejected, both records are set to REJECTED and an optional reason is stored for display to the customer.

​
Request body

​
orderId
string
required
The UUID of the order whose payment status is being updated.
​
submissionId
string
UUID of the specific PaymentSubmission to update. If omitted, all submissions on the order are updated.
​
status
string
required
Verification outcome. Accepted values: "CONFIRMED" or "REJECTED".
​
rejectionReason
string
Human-readable explanation shown to the customer when status is "REJECTED". Stored on the PaymentSubmission.rejectionReason field.

​
Response

{ "success": true }

​
Side effects

status valueOrder.statusPaymentSubmission.status
"CONFIRMED"CONFIRMEDCONFIRMED + verifiedAt timestamp set
"REJECTED"REJECTEDREJECTED + rejectionReason stored

​
Error responses

StatusCondition
400orderId or status missing.
401 / 403Caller does not hold the ADMIN role.
500Unexpected server error.

​
GET /api/payments/accounts

Returns all active PaymentAccount records. This endpoint is unauthenticated and is called during checkout to display the bank details customers must transfer funds to. If the database is unreachable, a built-in seed fallback (Banesco + Binance) is returned so checkout never breaks.

​
Response

{
  "success": true,
  "accounts": [
    {
      "id": "default-banesco-account",
      "bankName": "Banesco",
      "accountNumber": "01340001010001000101",
      "holderName": "Valeria Rojas",
      "holderId": "V-12345678",
      "phone": "04125555555",
      "instructions": "Realizar Pago Móvil o Transferencia al titular indicado. Registre el número de referencia y suba su comprobante.",
      "active": true
    },
    {
      "id": "default-binance-account",
      "bankName": "Binance",
      "accountNumber": "valeria.rojas@binance.com",
      "holderName": "Valeria Rojas",
      "holderId": "ID: 987654321",
      "phone": "04125555555",
      "instructions": "Realizar envío a la cuenta Binance Pay (correo o ID) indicada. Registre el número de referencia de la transacción.",
      "active": true
    }
  ]
}
​
success
boolean
Always true on success.
​
accounts
array
Array of active PaymentAccount objects. Only records with active: true are returned.

Build docs developers (and LLMs) love

Get started for freeTalk to us