Uso de la API de Facebook Pay

Cuando procesas pagos para Facebook Pay, debes notificar a Facebook sobre la actividad de transacciones de pago, como autorizaciones y reembolsos, invocando webhooks en la API de Facebook Pay. La actividad de transacciones de pagos aparece en la página de actividad de Facebook Pay de la cuenta de Facebook de un cliente.

Para aprender a usar API de Facebook, consulta Información general sobre la API Graph. Para obtener más información general, consulta Información general sobre la integración con Facebook Pay.

Incorporación

Para comenzar a usar las API de Facebook Pay, debes hacer lo siguiente:

• Completar los pasos generales de incorporación
• Revisar el procesamiento básico de tarjetas en Facebook Pay

Llamar a las API de Facebook Pay

Como parte de los pasos generales de incorporación, se crea una nueva aplicación en el portal para desarrolladores de Facebook. Después de crear tu aplicación, obtienes un identificador de app y una clave secreta de app para tu aplicación.

Para cada llamada que hagas a una API de Facebook Pay se requiere un token de acceso a la app derivado del identificador y de la clave secreta de la app. Envía el token de acceso a la app usando el encabezado Authorization, no un parámetro de consulta access_token. Las API de Facebook Pay rechazan llamadas con tokens de usuarios.

Por ejemplo, usa el siguiente código:

Authorization: OAuth <APP_ACCESS_TOKEN>

Firma

Cada solicitud HTTP a las API de Facebook Pay deben incluir un encabezado de solicitud FBPAY-SIGNATURE. El valor de este encabezado es un objeto de firma web JSON (JWS) con el algoritmo ES256, serialización compacta y una carga desconectada (según https://tools.ietf.org/html/rfc7515#appendix-F). El valor de la carga es el cuerpo de la solicitud HTTP POST. La clave de firma JWS se debe identificar con el encabezado x5c, que debe contener un certificado encadenado a la raíz de confianza del socio.

Ejemplo de una solicitud con una firma

curl -i -X POST \
  -H "Content-Type: application/json" \
  -H "FBPAY-SIGNATURE: eyJ4NWMiOlsiTUlJQmhEQ0NBU3FnQXdJQkFnSUJBVEFLQmdncWhrak9QUVFEQWpBaE1SOHdIUVlEVlFRRERCWndZWEowYm1WeUlITnBaMjVoZEhWeVpTQmpaWEowTUI0WERUSXdNRGN4TXpJeU1qVXpNRm9YRFRJME1ETXhNVEl5TWpVek1Gb3dJVEVmTUIwR0ExVUVBd3dXY0dGeWRHNWxjaUJ6YVdkdVlYUjFjbVVnWTJWeWREQlpNQk1HQnlxR1NNNDlBZ0VHQ0NxR1NNNDlBd0VIQTBJQUJBbkZ4MEdTSjJJT2RmaXBXYjBjMGcrQVU4ZWw4ekJ0VUtJMXVkc09pMzdrYXdSUUhZM1dvWGlkb0U4SDhzNXFSMkpqNmZBSllYTk1EV2NDYnYrVjBCdWpVekJSTUIwR0ExVWREZ1FXQkJUeDZQRkZIY3dhVGZ2OXFXc2VCL1NjMWFPbVZ6QWZCZ05WSFNNRUdEQVdnQlR4NlBGRkhjd2FUZnY5cVdzZUIvU2MxYU9tVnpBUEJnTlZIUk1CQWY4RUJUQURBUUgvTUFvR0NDcUdTTTQ5QkFNQ0EwZ0FNRVVDSVFDQURPc2dKWWp0V1ZvcTVGTko3N1NiQ3lrTjdWZXVJSkdqV29zQVVBTXdWUUlnVE5VL2ttcy83RzFVTHlnTUNFZVd6Y2JhM2sxWjg0QThGY2UxdDNhQ0ZsZz0iXSwiYWxnIjoiRVMyNTYifQ..cxJCDccrzkaxlZHxqZkqZo6zOF0lUjPikpoEkUuAbuyqegDGeSPFCccZS1TCygJdTJhpTajxnbg77Y5NnQdwMQ" "https://graph.andreyb.sb.facebook.com/v7.0/1001200005002/payment" \
  -d '{"notification":{"partner_merchant_id":"123e4567-e89b-12d3-a456-426614174000","container_id":"cGF5bWVudF9jb250YWluZAXI6MTIzNDU2NzhfX01FUkNIQU5UX1RFU1RfRTJFX19QU1BfVEVTVF8x","event_time":1582230020020,"type":"payment.updated"},"resource":{"partner_payment_id":"1234567890","status":"PENDING","created_time":1582230019010,"metadata":[]},"idempotence_token":"ddbdf2cf-d339-4b0b-a27e-4731d8d37c9d"}'

La solicitud previa codifica los siguientes datos:

{
  notification:
  {
    partner_merchant_id: '123e4567-e89b-12d3-a456-426614174000',
    container_id: 'cGF5bWVudF9jb250YWluZAXI6MTIzNDU2NzhfX01FUkNIQU5UX1RFU1RfRTJFX19QU1BfVEVTVF8x',
    event_time: 1582230020020,
    type: 'payment.updated'
  },
  resource:
  {
    partner_payment_id: '1234567890',
    status: 'PENDING',
    created_time: 1582230019010,
    metadata: []
  },
  idempotence_token: 'ddbdf2cf-d339-4b0b-a27e-4731d8d37c9d'
}

A continuación, se muestra la firma de la solicitud previa, Base64 y JSON, decodificada para mayor claridad:

base64url(
 json({
   "x5c": [
     "MIIBhDCCASqgAwIBAgIBATAKBggqhkjOPQQDAjAhMR8wHQYDVQQDDBZwYXJ0bmVyIHNpZ25hdHVyZSBjZXJ0MB4XDTIwMDcxMzIyMjUzMFoXDTI0MDMxMTIyMjUzMFowITEfMB0GA1UEAwwWcGFydG5lciBzaWduYXR1cmUgY2VydDBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABAnFx0GSJ2IOdfipWb0c0g+AU8el8zBtUKI1udsOi37kawRQHY3WoXidoE8H8s5qR2Jj6fAJYXNMDWcCbv+V0BujUzBRMB0GA1UdDgQWBBTx6PFFHcwaTfv9qWseB/Sc1aOmVzAfBgNVHSMEGDAWgBTx6PFFHcwaTfv9qWseB/Sc1aOmVzAPBgNVHRMBAf8EBTADAQH/MAoGCCqGSM49BAMCA0gAMEUCIQCADOsgJYjtWVoq5FNJ77SbCykN7VeuIJGjWosAUAMwVQIgTNU/kms/7G1ULygMCEeWzcba3k1Z84A8Fce1t3aCFlg="
   ],
   "alg": "ES256"
 })
) + // Protected Header
 "." +
 "" + // Payload is detached
 "." +
 "cxJCDccrzkaxlZHxqZkqZo6zOF0lUjPikpoEkUuAbuyqegDGeSPFCccZS1TCygJdTJhpTajxnbg77Y5NnQdwMQ" // Signature

Idempotencia

El campo idempotence_token se usa para evitar la ejecución duplicada de solicitudes cuando se intenta realizar solicitudes después fallas o errores de tiempo de espera agotado de la red. El token de idempotencia es un valor único generado por el cliente y este decide cómo lo genera. Por ejemplo, puedes usar el UUID V4 para generar un token de idempotencia.

Cuando una solicitud se completa con éxito, o cuando una llamada a la API devuelve resultados válidos, los datos de la respuesta se guardan con el token de idempotencia. Cuando una solicitud correcta se intenta de nuevo con un token de idempotencia usado previamente, la respuesta previamente guardada se devuelve sin volver a ejecutar código.

Cuando una solicitud produce un error, no se guardan resultados. Puedes intentar de nuevo la solicitud y usar el mismo token de idempotencia.

Si haces 2 solicitudes de forma consecutiva con el mismo token de idempotencia, solo una devuelve datos de respuesta.

Los tokens de idempotencia están pensados para ser transitorios y solo se usan para reintentar las llamadas de API en caso de fallas. Si, después de un tiempo, intentas de nuevo hacer una solicitud, podrías recibir una respuesta diferente respecto de la llamada anterior.

Se ignoran los parámetros de solicitud. Si cambias el contenido de la solicitud de alguna manera, se creará un nuevo token de idempotencia para la solicitud.

Conciliación por lotes

Cuando procesas pagos, notificas a Facebook sobre la actividad de transacciones de pago usando los webhooks de Facebook Pay. Al invocar webhooks, la actividad de transacciones de pago aparece en la página de actividad de Facebook Pay de la cuenta de Facebook de un cliente a la mayor brevedad.

Facebook captura las notificaciones con errores durante la conciliación por lotes y estas aparecen en la cuenta de Facebook del cliente posteriormente.

Para admitir la conciliación por lotes, carga cada día un archivo que contenga las notificaciones que enviaste a Facebook ese día. Incluye notificaciones correctas y fallidas. Para obtener información detallada sobre cómo subir un archivo a la API de Facebook, consulta Subir archivos a Facebook.

Administración de errores

Las API de Facebook Pay usan la administración de errores de la API Graph estándar.

Inicializar y actualizar comerciantes

Para inicializar un comerciante o actualizar sus datos, haz una solicitud POST a la API del comerciante y especifica los parámetros del comerciante.

Respuesta del comerciante

Una vez se hace una solicitud POST a la API del comerciante, una respuesta 200 OK indica que POST se procesó con éxito. El cuerpo de la respuesta indica el estado del comerciante, así sea ENABLED o DISABLED. Los modificadores de estado no vacíos proporcionan información adicional.

Una respuesta exitosa común tiene el siguiente aspecto:

{
    "status":"ENABLED",
    "status_modifiers":[]
}

Una respuesta para un comerciante que se encuentra temporalmente en proceso de selección tiene el siguiente aspecto:

{
    "status":"DISABLED",
    "status_modifiers":["PENDING_SCREENING"]
}

A continuación, se muestran los posibles modificadores de estado.

Parámetros del comerciante

Webhooks

Cuando tenga lugar cualquier autorización, captura, disputa, pago o reembolso, debes notificar a Facebook sobre una actividad de transacciones de pago invocando los webhooks de Facebook.

Una respuesta 200 OK indica que el webhook se procesó con éxito. No hay cuerpo de respuesta.

Si la invocación de un webhook falla, vuelve a intentar la invocación durante al menos 72 horas. Si la invocación falla de todas formas, la notificación se puede capturar después durante la conciliación por lotes.

A continuación, se ofrece un diagrama de relaciones de entidades para los recursos modelados en los webhooks de la API de Facebook. Las entidades en gris no forman parte de streams de trabajo actuales.

Notificación

Cada vez que invoques un webhook, incluye un parámetro de notificación en el cuerpo de la solicitud y detalles del tipo de notificación en el campo de recursos, como se describe en las secciones que siguen. La estructura general para la notificación es la siguiente:

{
  idempotence_token: '<your token>',
  notification:
  {
    ...
  },
  resource:
  {
    ...
  }
}

Parámetro de notificación

Notificar autorizaciones

Haz una solicitud POST a notify_authorizations a fin de notificar a Facebook sobre la actividad de autorización para una transacción de pago.

Recurso de autorización

Notificar capturas

Haz una solicitud POST a notify_captures a fin de notificar a Facebook sobre la actividad de captura para una transacción de pago.

Capturar recurso

Notificar disputas

Haz una solicitud POST a notify_disputes a fin de notificar a Facebook sobre la actividad de disputa para una transacción de pago.

Recurso de disputa

Notificar pagos

Haz una solicitud POST a notify_payments a fin de notificar a Facebook sobre la actividad de pago para una transacción de pago.

Recurso de pago

Notificar reembolsos

Haz una solicitud POST a notify_refunds a fin de notificar a Facebook sobre la actividad de reembolso para una transacción de pago.

Recurso de reembolso

Objeto de importe de notificación

Usa el objeto “amount” a fin de representar un valor monetario en una divisa específica para notificaciones de autorizaciones, capturas, disputas y reembolsos.

Objeto “amount”

Objeto de error de notificación

Si se produce un error cuando proceses una autorización, captura, pago o reembolso, incluye un objeto error en el resource para brindar información sobre el error.

Objeto de error