Create a Payin

Collect funds from a third party (end-user) to be tokenized into stablecoin tokens.

warning

This API spec is a Work in Progress and is subject to change during Q2 2025.

Request

Endpoint

POST /v1/payins

Scope

payins:create

Structure

Name	Type	Description
token	string	The stablecoin token to be used for the payin. Valid values are: • COPM for Colombian Pesos.
amount	string	The amount of funds to be collected and tokenized.
payment	<payment>	Payment object (method, details, etc.)
destination_source_id	uuid	The ID of the Customer's wallet to send the stablecoin tokens to.
purpose	string	A description of why the payin is being made.
final_url	string	URL to redirect the end-user to, after the Payin's payment is completed. ID of the Payin will be appended as a query parameter to this URL.
recipient	<recipient>	The end-user or ultimate beneficiary who's completing the payment for the payin. See below for more details.

The payment object

This object is filled depending on the payment method chosen by the Customer.

Required attributes for PSE

Name	Type	Description
method	string	PSE (Pagos Seguros En línea)
bank	string	The bank to be used for the payin.

The recipient object

Name	Type	Description
full_name	string	The full name of the recipient.
legal_identifier_type	string	The type of legal ID of the recipient. Valid values are: • CC for Colombian Cedula de Ciudadanía. • CE for Colombian Cedula de Extranjería. • NIT for Colombian NIT. • PP for Passport.
legal_identifier	string	The legal ID of the recipient.
country_iso	string	The ISO 3166-1 alpha-2 country code of the recipient. Valid values are: • CO for Colombia.
email	string	The email address of the recipient.

Example JSON Request Body

{
  "token": "COPM",
  "amount": "127000",
  "destination_source_id": "2af83836-43ea-407b-ab4e-9c64ee817b28", // Customer's Wallet
  "purpose": "Top-up on behalf of John Doe",
  "final_url": "https://yoursite.com/payin-completed",
  "payment": {
    "method": "PSE",
    "bank": "BANCO_FALABELLA"
  },
  "recipient": {
    "full_name": "John Doe",
    "legal_identifier_type": "CC",
    "legal_identifier": "1099075610",
    "country_iso": "CO",
    "email": "john@example.com"
  }
}

Response

The important thing to note in the received response, is the action field, which states the next action to be taken by the end-user completing the Payin.

Currently, the only possible action is to redirect the end-user (recipient) to a URL where they will complete the payment for the Payin. For this, you will need to use the action.redirect_url field, so that the end-user is redirected to such URL.

Structure

Name	Type	Description
output	Payin	The Payin object.
code	string	The response status code text.

The action object

Below are the attributes of the action object when the action type is REDIRECT:

Name	Type	Description
type	string	The type of action to be taken. Currently, the only possible value is REDIRECT.
redirect_url	string	This URL is the one that you need to redirect the end-user (recipient) to, in order for them to complete the payment.

Once the end-user (recipient) has completed the payment, they will be redirected to the final_url that you provided when creating the Payin.

Example Response

{
  "output": {
    "id": "ffb50d6c-09f1-4f08-9b91-cbce466bed52",
    "action": {
      "type": "REDIRECT",
      "redirect_url": "https://api.minteo.finance/payins/redirect/ffb50d6c-09f1-4f08-9b91-cbce466bed52"
    },
    "status": "PENDING",
    // ^ Newly returned attributes -----
    "destination_source_id": "2af83836-43ea-407b-ab4e-9c64ee817b28", // Customer's Wallet
    "amount": "127000",
    "token": "COPM",
    "purpose": "Top-up on behalf of John Doe",
    "final_url": "https://yoursite.com/payin-completed",
    "payment": {
      "method": "PSE",
      "bank": "BANCO_FALABELLA"
    },
    "recipient": {
      "full_name": "John Doe",
      "legal_identifier_type": "CC",
      "legal_identifier": "1099075610",
      "country_iso": "CO",
      "email": "john@example.com"
    }
  },
  "code": "CREATED"
}