Skip to main content
This section explains the core concepts you’ll encounter when working with Cashii’s Remote Payments API.

​
Remote Payments

A Remote Payment is the primary mechanism for integrations. It represents a payment request initiated by your application (e.g., your backend server) and fulfilled by a user through the Cashii ecosystem (either via the Cashii app or a supported bank card). Think of it as creating a payment order that a user can then act upon.

​
Attributes of a Remote Payment

A Remote Payment object contains the following key attributes:
  • id: A unique 16-digit identifier automatically generated by Cashii for the payment request.
  • amount: The payment amount specified in the smallest currency unit (cents for USD/EUR, kuruş for TRY, etc.). For example, 10098 represents 100.98.
  • currency: The three-letter ISO currency code (e.g., USD, EUR, SYP, TRY).
  • note: A brief description or memo for the payment, visible to the involved parties.
  • metadata: A flexible JSON object where you can store additional information relevant to your application (e.g., {"orderId": "ORD-12345", "customerId": "CUST-678"}). This is useful for tracking and reconciliation.
  • status: Indicates the current state of the payment. See Payment Statuses for details.
  • from: (Available after payment) The Cashii account number from which the payment was made.
  • to: The Cashii account number (associated with your commercial account/API key) to which the payment is credited.
  • payable_to: (Optional) You can restrict the payment to be fulfilled only by a specific Cashii account number.

​
Payment Statuses

A Remote Payment progresses through several statuses:
  • pending: The initial state after creation. The payment request has been generated but not yet acted upon by the user.
  • paid: The user has successfully completed the payment.
  • canceled: The payment was explicitly canceled (either by the user or potentially via API in future implementations).
  • rejected: The payment attempt was rejected (e.g., insufficient funds, security checks).
  • refunded: The payment was successfully made but later refunded.

​
Standard Workflow

The following diagram illustrates the typical flow of information when a user initiates a payment via Cashii in your application:
  1. User Action: User clicks “Pay with Cashii” in your application (frontend).
  2. Request to Backend: Your application sends payment details (amount, currency, etc.) to your backend server.
  3. Create Remote Payment: Your backend server authenticates with the Cashii API (using your API key) and sends a request to create a Remote Payment.
  4. Receive Payment ID: Cashii API validates the request and responds with a unique id for the new Remote Payment (status is pending).
  5. Return ID to Frontend: Your backend server returns the paymentId to your application.
  6. Redirect User: Your application redirects the user to the Cashii Payment Page, including the paymentId. See Payment Flow for details.
  7. User Pays: The user completes the payment on the Cashii page/app.
  8. User Redirected Back: Cashii redirects the user back to the redirectUrl you specified, appending payment status information. Your application should verify this status with your backend.

​
Technical Workflow Detail

This diagram shows more backend interactions, including database updates: Key steps include:
  • Storing the paymentId in your database after creation (Step 5) to track the order and potentially prevent duplicate requests.
  • Verifying the final payment status by having your application query your backend (Step 10), which in turn queries the Cashii API (Step 11) using the paymentId before confirming success to the user (Step 12).