Checkout API

Estable

Integra el flujo de checkout B2B creando una orden y luego ejecutando el pago, confirmación o reversa según corresponda.

Guías de integración

¿Cómo funciona la Integración SDK?

1
Paso 1: Solicitar Access Token usando tus credenciales anteriormente creadas para el entorno correspondiente
Primero solicita un token de acceso con tu usuario y contraseña de integración. Ese token luego se pega en el campo data-access-token.
2
Pegar el bloque del botón en tu sitio
Copia el bloque HTML del checkout en la página donde querés mostrar el botón de pago.
3
Definir URLs de retorno
Configura las URLs de éxito, error y retorno para que el comprador vuelva correctamente a tu sitio luego del pago.

Paso 1: Solicitar Access Token usando tus credenciales anteriormente creadas para el entorno correspondiente

const http = require('https');

const options = {
  method: 'POST',
  hostname: 'api.developer-portal.personalpay.dev',
  path: '/oauth/token',
  headers: {
    'content-type': 'application/json',
    'x-request-id': '12323123',
  },
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on('data', function (chunk) {
    chunks.push(chunk);
  });

  res.on('end', function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
    // tomar access_token de la respuesta y setearlo en data-access-token
  });
});

req.write(
  JSON.stringify({
    user: '{{EMAIL_INTEGRADOR}}',
    password: '{{PASSWORD_INTEGRADOR}}',
  })
);
req.end();

Implementación del SDK en tu sitio

Paso 2: Insertar el botón y script del SDK

Pega este bloque en tu HTML donde quieras renderizar el botón. Reemplaza los datos entre {{ }} con los tuyos.

<div 
    id="checkout-pay"
    data-access-token="{{ACCESS_TOKEN}}"
    data-cart-id="{{CART_ID}}"
    data-point="{{POINT_ID}}"
    data-seller-session-id="{{SELLER_SESSION_ID}}"
    data-seller-channel="{{SELLER_CHANNEL}}"
    data-total-amount="12.00"
    data-product-name="Producto de prueba"
    data-product-quantity="1"
    data-additional-data='{"a": 1}'
    data-callback-url="https://{{TU_SITIO}}/callback"
    data-callback-url-fail="https://{{TU_SITIO}}/callback-fail"
    data-callback-url-success="https://{{TU_SITIO}}/callback-success"
    data-callback-function="callbackFunction">
  </div>

  <script defer="defer" src="https://checkout.personalpay.dev/build/static/js/checkout-pay.js"></script>

Paso 3: Configurar callback function

Al hacer click en el botón, el SDK redirige al checkout de Personal Pay y luego vuelve a tus URLs de retorno.

<script>
function callbackFunction(data) {
  console.log('Evento SDK:', data);
  // Sugerencia: registrar este evento en tu observabilidad
}
</script>

Referencia de API

POST

/v1/api-checkout/order

Crea una orden de checkout.

Parámetros

Campo	Tipo	Requerido	Descripción
`sellerSessionId`	string	Sí	Sesión del seller en su plataforma.
`flowType`	string	Sí	Contexto del flujo: desktop o mobile.
`cartId`	string	Sí	Identificador del carrito del seller.
`sellerChannel`	string	Sí	Canal configurado para el seller.
`orderData`	object	Sí	Datos de la orden (point, totalAmount, productName, productQuantity, additionalData).

POST

/v1/api-checkout/payment/confirm/:id

Confirma el pago de una orden.

Parámetros

Campo	Tipo	Requerido	Descripción
`id`	string	Sí	ID de orden a confirmar (path param).
`storeId`	string	Sí	Store ID asociado a la orden.
`amount`	integer	Sí	Monto a confirmar.

POST

/v1/api-checkout/payment/reverse/:id

Inicia la reversa de una orden.

Parámetros

Campo	Tipo	Requerido	Descripción
`id`	string	Sí	ID de orden a reversar (path param).
`storeId`	string	Sí	Store ID asociado a la orden.
`amount`	integer	Sí	Monto a reversar.

Estados de Orden

Estado	Descripción
`pending-confirm`	Estado intermedio cuando la orden necesita confirmación. En este punto el pagador ya fue debitado.
`payment-confirmed`	Monto acreditado al seller.
`payment-reversed-pending`	Proceso de reversa iniciado.
`payment-reversed`	Reversa completada y dinero acreditado nuevamente al pagador.

Manejo de errores

Código	Descripción
`10021001`	La orden no está pendiente de confirmación.
`10021002`	La orden no puede confirmarse porque expiró la ventana de confirmación.
`10022001`	El monto de la orden debe coincidir con el enviado en la request.
`10023001`	El seller que envía la solicitud no coincide con el seller de la orden.
`10024001-10024002`	Error de tipado o campos requeridos vacíos en la request.
`10025001-10025002`	Número de orden inexistente o no encontrado.
`10026001`	La orden no tiene transacciones disponibles para reversa.
`10027001`	La orden ya fue reversada previamente.
`10028001`	La orden no puede ser reversada.
`10029001`	La orden excedió el límite de días permitido para reversa.
`10030001`	El seller no tiene una cuenta disponible.
`10030101`	El seller no tiene fondos suficientes para ejecutar la reversa.
`10032002`	El intervalo de búsqueda no puede superar 15 días.
`10032102`	La fecha inicial de búsqueda no puede ser mayor a la fecha actual.
`10032202`	La fecha final de búsqueda no puede ser mayor a la fecha actual.
`10032302`	Para búsqueda por fecha se deben enviar fecha inicial y final.
`10033002`	El seller debe estar correctamente onboardeado.
`10034002`	Debe enviarse sellerCartId o orderId para la consulta.
`10035002`	El id de la orden debe ser numérico y mayor a 0.
`10036002`	No hay órdenes para el criterio de búsqueda (404 en listar órdenes).

Próximo Paso

Configurá tu credencial

Generá tus credenciales de integración para empezar a operar.

Guías de integración

¿Cómo funciona la Integración SDK?

Paso 1: Solicitar Access Token usando tus credenciales anteriormente creadas para el entorno correspondiente

Pegar el bloque del botón en tu sitio

Definir URLs de retorno

Paso 1: Solicitar Access Token usando tus credenciales anteriormente creadas para el entorno correspondiente

Implementación del SDK en tu sitio

Paso 2: Insertar el botón y script del SDK

Paso 3: Configurar callback function

Referencia de API

Estados de Orden

Manejo de errores

Próximo Paso

Configurá tu credencial

¿Cómo funciona la Integración SDK?

Paso 1: Solicitar Access Token usando tus credenciales anteriormente creadas para el entorno correspondiente

Pegar el bloque del botón en tu sitio

Definir URLs de retorno

Paso 1: Solicitar Access Token usando tus credenciales anteriormente creadas para el entorno correspondiente

Implementación del SDK en tu sitio

Paso 2: Insertar el botón y script del SDK

Paso 3: Configurar callback function