Cuando vayas a actualizar tu integración antigua a la API nueva, tendrás que ajustar el controlador de webhooks para administrar los tipos de webhook nuevos que te enviamos.
También hemos modificado algunas de las acciones que enviábamos en el sistema antiguo. A continuación puedes encontrar una relación de dichos cambios, así como de las acciones nuevas que pueden resultarte de interés:
Autorizaciones > Mandatos
Ahora, las autorizaciones son mandatos. Los mandatos son mucho más flexibles, puedes crear pagos puntuales o suscripciones con el mismo mandato y los mandatos pueden tener varias suscripciones asociadas. No hace falta que el cliente vuelva a autorizar los pagos o suscripciones nuevos de un mandato.
API heredada: Acciones de autorizaciones previas/suscripciones | API nueva: Acciones de mandatos | Descripción de la acción |
cancelled | cancelled | El mandato ha sido cancelado, ya sea por el cliente a través de su banco o por la API, o automáticamente si se cierra la cuenta bancaria. |
expired | expired | No se ha realizado ningún intento de cobro del mandato en más de 13 meses. Como resultado de ello, ha caducado y ya no se pueden realizar otros cobros con él. Si quieres seguir aceptando pagos de este cliente, debes pedirle permiso y utilizar el extremo de renovación. |
API nueva: Acciones de mandatos adicionales | Descripción de la acción |
created | El mandato se ha creado. |
customer_approval_granted | El mandato requiere una autorización adicional del cliente (por ejemplo, la autorización de un segundo firmante) y que se haya recibido la aprobación. |
customer_approval_skipped | En un principio se creía que el mandato requería una autorización adicional del cliente (por ejemplo, la autorización de un segundo firmante), pero se ha omitido la aprobación (por ejemplo, porque el mandato se marcó erróneamente como que necesitaba una segunda firma). |
active | El banco del cliente ha configurado correctamente el mandato. |
failed | El mandato no se ha podido configurar, normalmente debido a que la cuenta bancaria especificada no acepta pagos de domiciliaciones bancarias o está cerrada. |
transferred | El mandato se ha transferido a una cuenta bancaria diferente. El evento incluirá links[previous_customer_bank_account] y links[new_customer_bank_account], y puede que el mandato se haya vuelto a enviar, dependiendo de cómo hayan tratado la transferencia los bancos intervinientes. |
submitted | El mandato se ha enviado a los bancos y debería pasar al estado activo al cabo de unos días, a menos que el banco rechace la solicitud. |
resubmission_requested | El extremo de renovación del mandato ha hecho una solicitud de reenvío del mandato. |
reinstated | El mandato se ha vuelto a activar, después de haber sido cancelado o haber caducado. Esto se puede deber a que el banco del cliente quiere anular una notificación de cancelación o de caducidad que había enviado anteriormente, o a que el mandato se ha renovado correctamente por medio del extremo de renovación. |
replaced | El mandato ha sido cancelado y sustituido por un mandato nuevo (por ejemplo, porque el acreedor ha cambiado a un nuevo número de usuario del servicio). El evento incluirá links[new_mandate] con el identificador del mandato nuevo. |
Facturas > Pagos
La API heredada permitía crear facturas puntuales o una serie de facturas puntuales con una autorización previa. Ahora, las facturas se denominan pagos, y un pago se puede crear con carácter puntual o como parte de una suscripción.
API heredada: Acciones de facturas | API nueva: Acciones de pagos | Descripción de la acción |
created | created | El pago se ha creado. |
paid | confirmed | El pago se ha cobrado de la cuenta bancaria del cliente y actualmente está en poder de GoCardless. El cobro de un pago puede tardar hasta cinco días laborables y, posteriormente, se retendrá durante un breve intervalo de tiempo antes de pasar al estado paid_out. |
withdrawn | paid_out | El pago ha salido de GoCardless y se ha enviado a la cuenta bancaria del acreedor. |
failed | failed | No se pudo cobrar el pago, normalmente debido a que el cliente no tenía suficientes fondos disponibles. GoCardless no volverá a intentar tramitar el pago automáticamente. |
cancelled | cancelled | El pago se canceló. |
refunded | (enviado como un objeto de reembolso)** | |
chargedback | charged_back | El cliente solicitó a su banco el reembolso del pago de conformidad con la garantía de domiciliación bancaria y se ha devuelto al cliente. |
retried | resubmission_requested | Se realizó una solicitud para reenviar el pago por medio del extremo de reintentar pago. |
API nueva: Acciones de pagos adicionales | Descripción de la acción |
submitted | El pago se ha enviado a los bancos. Tardará unos días en cobrarse o ser rechazado. |
late_failure_settled | El pago tuvo un fallo tardío cuando ya se había desembolsado y se ha cargado a un desembolso. |
chargeback_cancelled | El banco del cliente ha cancelado la solicitud de devolución. Esto se produce casi siempre a petición del cliente. |
chargeback_settled | El pago fue devuelto después de haber sido desembolsado y se ha cargado a un desembolso. |
**Ahora, los reembolsos están representados por un recurso propio. Si se reembolsa un pago, el recurso del pago se mantendrá en el estado confirmado y se creará un recurso de reembolso independiente del pago.
API nueva: Acciones de reembolsos | Descripción de la acción |
created |
Se ha creado un reembolso. El details[cause] será payment_refunded, mientras que el details[origin] será api. |
paid | Se ha pagado el reembolso a tu cliente. El details[cause] será refund_paid, mientras que el details[origin] será gocardless. |
refund settled | El reembolso se ha deducido de un desembolso. El details[cause] será refund_settled, mientras que el details[origin] será gocardless. |
Ahora se pueden crear suscripciones a partir de un mandato. Recibirás las siguientes acciones de webhooks:
API nueva: Acciones de suscripciones | Descripción de la acción |
created | La suscripción se ha creado. |
customer_approval_granted | La suscripción requería una autorización adicional del cliente antes de que se pudiera activar y se ha concedido dicha aprobación. |
customer_approval_denied | La suscripción requería una autorización adicional del cliente antes de que se pudiera activar y se ha denegado dicha aprobación. |
payment_created | Se ha creado un pago por medio de esta suscripción. |
cancelled | Esta suscripción se ha cancelado. No se creará ningún otro pago. |
finished | Esta suscripción ha finalizado. No se creará ningún otro pago. |
Desembolsos
La API nueva sigue permitiendo hacer consultas sobre los desembolsos que recibes de GoCardless. Además, hemos añadido algunos pasos para ayudarte a conciliar los desembolsos con los eventos, de modo que podrás obtener un listado de los pagos de un desembolso específico a través de la API.
API nueva: Acciones de desembolsos | Descripción de la acción |
paid | GoCardless ha transferido el desembolso a la cuenta bancaria del acreedor. El details[cause] será siempre payout_paid, mientras que el details[origin] será gocardless. |
Formato de los webhooks
La API heredada enviaba webhooks sobre el estado de una factura, autorización previa o suscripción. La API nueva envía webhooks que contienen mucha más información y se pueden enviar a varios extremos. Cuando un recurso cambia de estado, registramos un evento. Los eventos se agrupan en matrices y se envían como webhooks mediante POST.
Ejemplo de webhook antiguo de autorización previa:
{
"payload": {
"resource_type": "pre_authorization",
"action": "cancelled",
"pre_authorizations": [{
"id": "AKJ398H8KBOOO3",
"status": "cancelled",
"uri": "https://gocardless.com/api/v1/pre_authorizations/AKJ398H8KBOOO3"
}, {
"id": "AKJ398H8KBOOOA",
"status": "cancelled",
"uri": "https://gocardless.com/api/v1/pre_authorizations/AKJ398H8KBOOOA"
}],
"signature": "f6b9e6cd8eef30c444da48370e646839c9bb9e1cf10ea16164d5cf93a50231eb"
}
}
Ejemplo de webhook de mandato de la API nueva:
{
"events": [
{
"id": "EVTESTWKH4MPNG",
"created_at": "2017-04-25T11:20:47.542Z",
"resource_type": "mandates",
"action": "cancelled",
"links": {
"mandate": "MD123"
},
"details": {
"origin": "api",
"cause": "mandate_cancelled",
"description": "The mandate was cancelled at your request."
},
"metadata": {}
}
]
}
También puedes encontrar una herramienta útil para hacer pruebas a los webhooks nuevos en la pestaña de desarrolladores de la cuenta de pruebas nueva y en el panel de control del entorno real. Desde el apartado para desarrolladores, haz clic en "Enviar webhook de prueba" para enviar al extremo de webhooks cualquier webhook que puedas recibir.