MACH Pay API (0.1.0)

Download OpenAPI specification:Download

MACH Pay API. Organizada en torno a REST: URLs predecibles y orientadas a recursos, acepta cuerpos de solicitudes form-encoded, retorna respuestas codificadas en JSON, y usa estándar HTTP para los códigos de respuesta, autenticación y verbos.

Para realizar llamadas en modo sandbox, se debe llamar a https://biz-sandbox.soymach.com, y en modo producción se debe llamar a https://biz.soymach.com

La API de MACH Pay está construida para ser utilizada como una plataforma de pagos, en donde sus clientes pueden usar la aplicación MACH para pagar en su comercio.

Authentication

bearerAuth

Token de acceso que debe adjuntarse en el header Authorization de cada uno de los requests. E.g: "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"

Este token se puede generar a través de la plataforma MACH Pay, en Configuraciones > Llaves. Tras generar una llave, la misma no se podrá recuperar, ya que no es guardada en sistema y no se puede volver a generar.

Security Scheme Type HTTP
HTTP Authorization Scheme bearer
Bearer format "JWT"

Webhooks

MACH Pay permite configurar webhook endpoints para notificar a una URL acerca de eventos que ocurren en su cuenta MACH Business. Para configurar un webhook, se debe ingresar a la plataforma de MACH Pay, en Coonfiguraciones > Webhooks

Cuando (por ejemplo) un usuario autoriza una compra en su sitio, creada a través de la BusinessPayments API, MACH Pay puede notificarle a una URL registrada la ocurrencia del evento, con su información correspondiente. MACH Pay enviará un objeto a través de una solicitud HTTP POST, ante lo cual su endpoint debería retornar un estado HTTP 2xx. Toda otra respuesta notifica a MACH Pay que la URL registrada no recibió el webhook correctamente, y respuestas con estado 503 y 504 son re-intentadas durante 24 horas, para luego ser marcadas como fallidas.

Un ejemplo del objeto que envía MACH Pay al completarse un pago (y que se encuentra en el body de la solicitud) es el siguiente:

{
  "event_name": "business-payment-completed",
  "event_resource_id": "12685e38-ef64-4cff-b51a-8a4fe649e3b6"
}

En este payload de ejemplo, el campo event_resource_id es un string que identifica al BusinessPayment que fue completado con el evento. Use ese valor para llamar al endpoint Obtener un BusinessPayment descrito anteriormente, que retornará toda la información del pago recién completado.

BusinessPayments

Crear un BusinessPayment

Crea un objeto de tipo BusinessPayment.

Este endpoint se usa para poder recolectar un pago por parte de un usuario. Una vez creado el objeto, use la url entregada para crear y mostrar un código QR o un deeplink al usuario, mediante el cual este último podrá pagar o rechazar el pago usando la app MACH.

Puede adjuntar información relevante para su negocio dentro del objeto metadata en el cuerpo de la solicitud. Este campo quedará adjunto al BusinessPayment y será retornado en todas las llamadas.

Request Body schema: application/json
payment
object

Responses

201

BusinessPayment creado con éxito.

500

Ha ocurrido un problema interno

post/payments
/payments

Request samples

Content type
application/json
Example
Copy
Expand all Collapse all
{
  • "payment":
    {
    }
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "token": "f1c85ae1-bb7f-4855-a4f4-ba144bcf7f35",
  • "url": "machapp://pay-biz/payment/f1c85ae1-bb7f-4855-a4f4-ba144bcf7f35",
  • "amount": 3990,
  • "message": "DJI Mavic Pro 7",
  • "title": "DJI Chile",
  • "is_message_editable": true,
  • "is_amount_editable": true,
  • "created_at": "2019-07-19 15:22:13.219Z",
  • "expires_at": "2019-07-19 15:27:13.219Z",
  • "status": "PENDING",
  • "metadata":
    {
    }
}

Obtener un BusinessPayment

Obtiene los detalles de un BusinessPayment previamente creado.

path Parameters
token
required
string
Example: dd6af8f6-4ba0-47d9-8c38-a4313e08b456

Identificador único del objeto BusinessPayment. Obtenido a partir de la llamada de creación de un nuevo pago.

Responses

200

BusinessPayment encontrado

404

El recurso solicitado no fue encontrado

500

Ha ocurrido un problema interno

get/payments/{token}
/payments/{token}

Response samples

Content type
application/json
Example
Copy
Expand all Collapse all
{
  • "token": "f1c85ae1-bb7f-4855-a4f4-ba144bcf7f35",
  • "url": "machapp://pay-biz/payment/f1c85ae1-bb7f-4855-a4f4-ba144bcf7f35",
  • "amount": 3990,
  • "message": "DJI Mavic Pro 7",
  • "title": "DJI Chile",
  • "is_message_editable": true,
  • "is_amount_editable": true,
  • "created_at": "2019-07-19 15:22:13.219Z",
  • "expires_at": "2019-07-19 15:27:13.219Z",
  • "status": "PENDING",
  • "metadata":
    {
    }
}

Reversar un BusinessPayment

Un BusinessPayment puede ser reversado cuando está en estado COMPLETED, y solo en una ventana de tiempo de 5 minutos después de haber transicionado a dicho estado (o sea, cuando el usuario autorizó la compra).

Una vez reversado el pago, el dinero descontado del saldo del usuario producto de la compra es automáticamente restituido, y todos los registros de compras son actualizados. Tarifas pueden aplicar a los montos reversados.

path Parameters
token
required
string
Example: dd6af8f6-4ba0-47d9-8c38-a4313e08b456

Identificador único del objeto BusinessPayment. Obtenido a partir de la llamada de creación de un nuevo pago.

Responses

200

BusinessPayment reversado con éxito.

400

Ha ocurrido un error de negocio o de validación.

500

Ha ocurrido un problema interno

post/payments/{token}/reverse
/payments/{token}/reverse

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "token": "f1c85ae1-bb7f-4855-a4f4-ba144bcf7f35",
  • "url": "machapp://pay-biz/payment/f1c85ae1-bb7f-4855-a4f4-ba144bcf7f35",
  • "amount": 3990,
  • "message": "DJI Mavic Pro 7",
  • "title": "DJI Chile",
  • "is_message_editable": true,
  • "is_amount_editable": true,
  • "created_at": "2019-07-19 15:22:13.219Z",
  • "expires_at": "2019-07-19 15:27:13.219Z",
  • "completed_at": "2019-07-19 15:23:13.219Z",
  • "reversed_at": "2019-07-19 15:26:13.219Z",
  • "status": "REVERSED",
  • "metadata":
    {
    }
}