Create Card Pushpayment (New)

In this documentation you will be able to see all the especifications that are needed to create a Pushpayment or Payouts to cards.

This API is only enabled for Peru. This method is only enabled for VISA cards issued by Peruvian banks.

This endpoint is available to all merchants who wish to perform payouts to cards. The service provides a user interface (UI) where the beneficiary can securely enter their card details. To enable this flow, the merchant must specify "accountType": "Card" in the request. Once the card data is entered, the card is tokenized and the payout order is executed to the corresponding card.

Below is a detailed description of the integration flow that must be followed to correctly implement this service:

Components & Integration Flow

1. The user clicks "Withdraw funds" on the merchant's site.

2. The site embeds an iframe pointing to its backend.

3. The backend requests the iframe from Monnet via REST API, using api-key and api-secret signed with HMAC-SHA256.

4. Monnet generates the payout and responds with the iframe + JWT for subsequent frontend requests.

5. The iframe is rendered by the merchant in the frontend and connects via WebSocket to Monnet.

6. The iframe displays a card tokenization form and sends the token via REST API (using the previously issued JWT).

7. Monnet sends an Iframe event message indicating process status: ok or fail.

The API keys used in this endpoint are the same as those used for the other endpoints.

Method: POST

URL: https://api.payout.monnet.io/api-payout-plus-real-time/{merchantId}

Request Monnet iframe for CARD payout

post

Authorizations

monnetAuth

monnet-api-keystringRequired

Path parameters

merchantIdstringRequired

timestampintegerRequiredExample: 1717689600

Query parameters

embed-jwtbooleanOptionalDefault: true

proxy-requestsbooleanOptionalDefault: false

Body

application/json

countrystringRequiredExample: PER

amountintegerRequiredExample: 50001

currencystringRequiredExample: PEN (Only available PEN or USD)

orderIdstringRequiredExample: BJB_dcb7f190-dfe2-4f45-83b1-86345e0b6d1f

timeoutUrlstringRequiredExample: https://www.test.com

merchantLogostringOptionalExample: https://bukwebapp-enterprise-peru.s3.amazonaws.com/1477f69a-81f3-4930-87fd-340c1aa0cb07/generals/icono_grande_menu_lateral/icono_grande_menu_lateral.png?v=1682353126

expirationTimestringOptional

Time in minutes before the iframe expires

Example: 03

Responses

200

Iframe created successfully

application/json

400

Bad request (missing fields or invalid data)

401

Unauthorized (invalid signature or API key)

500

Internal server error

post

/api-payout-plus-real-time/{merchantId}

HTTPcURLJavaScriptPython

POST /api-payout-plus-real-time/{merchantId} HTTP/1.1
Host: api.payout.monnet.io
monnet-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 530

{
  "country": "PER",
  "amount": 50001,
  "currency": "PEN (Only available PEN or USD)",
  "orderId": "BJB_dcb7f190-dfe2-4f45-83b1-86345e0b6d1f",
  "beneficiary": {
    "name": "Juan",
    "lastName": "Prueba",
    "email": "[email protected]",
    "document": {
      "type": 4,
      "number": 20629932888
    }
  },
  "destination": {
    "bankAccount": {
      "accountType": 5
    }
  },
  "timeoutUrl": "https://www.test.com",
  "merchantLogo": "https://bukwebapp-enterprise-peru.s3.amazonaws.com/1477f69a-81f3-4930-87fd-340c1aa0cb07/generals/icono_grande_menu_lateral/icono_grande_menu_lateral.png?v=1682353126",
  "expirationTime": "03"
}

{
  "iframe": "text",
  "jwt": "text"
}

The parameters embed-jwt and proxy-requests must not both be set to False simultaneously.

Request Example:

{
  "country": "PER",
  "amount": 50001,
  "currency": "PEN",
  "orderId": `BJB_${crypto.randomUUID()}`,
  "beneficiary": {
    "name": "Juan",
    "lastName": "Prueba",
    "email": "[email protected]",
    "document": {
      "type": 4,
      "number": "20629932888"
    }
  },
  "destination": {
    "bankAccount": {
      "accountType": 5,
    }
  },
  "timeoutUrl": "https://www.test.com",
  "merchantLogo": "https://www.test.com",
  "expirationTime": "03"
}

This method is only available for accountType = 5.

Response Example:

17KB

Example Responde.txt

Open

Iframe Events

The iframe communicates events using the JavaScript postMessage system:

{ topic: "event_name", data: {} }

Note: The data variable is currently empty, but it may be used in the future for additional information.

Available Events:

topic	Meaning
mps-payout-finished-timeout	Payout timed out (It is triggered after 15 minutes without receiving information)
mps-payout-finished-ok	Payout completed successfully
mps-payout-finished-fail	Payout failed

The iframe events are not exclusive to the information sent via the webhook. The transaction response (status, error messages, reasons) will be received through the webhook.