API de Apex para desarrolladores

Q: ¿Puedo crear clientes y métodos de forma masiva para una migración?

Crea los registros con una carga de datos y luego llama a createPayCustomer y createPayMethod desde un batch, un registro por ejecución, dentro de los límites de frecuencia de Payload.

Todo lo que hacen las pantallas de REDA Pay también está disponible para Apex en tu organización mediante una sola clase global. Úsala cuando un flujo no alcance: una página de pago personalizada, un script de migración que registra en Payload a clientes existentes, una integración que debe procesar una orden y leer el resultado de forma síncrona.

Antes de empezar

Eres un desarrollador de Salesforce con el permiso Author Apex y trabajas en un sandbox contra el entorno de prueba de Payload.
El usuario que ejecuta el código necesita el conjunto de permisos de REDA Pay para la operación (Admin User para las operaciones de configuración; Transaction Manager para anular y reembolsar) y, para los desembolsos, REDA Pay - Enable Disbursements.
Todos los métodos hacen una llamada a Payload. Llámalos desde un contexto que permita llamadas externas (un método future, queueable o batch, o un controlador sin trabajo pendiente sin confirmar).

La clase

Todos los métodos son estáticos en rpay.PayAPIGlobal y devuelven un rpay.TransactionResult.

Método	Qué hace
`createPayCustomer(Id payCustomerId)`	Registra el Pay Customer en Payload y guarda el identificador de cliente
`updatePayCustomer(Id payCustomerId)`	Envía a Payload el nombre, el correo y el teléfono del cliente
`createPayMethod(Id payMethodId, rpay.PayMethodWrapper details)`	Registra una tarjeta o cuenta bancaria para un registro Pay Method existente y guarda el token y los datos descriptivos
`deletePayMethod(Id payMethodId)`	Quita el método en Payload; el registro se conserva, marcado como eliminado
`processPayOrder(Id payOrderId, rpay.PayMethodWrapper details)`	Procesa una orden Immediate. Pasa `details` para registrar en el proceso una tarjeta o cuenta nueva, o `null` para usar el Pay Method registrado de la orden
`voidTransaction(Id transactionId, Date voidedDate, String voidingReason)`	Anula una transacción procesada y sin fondear
`refundTransaction(Id transactionId, Decimal refundAmount, String description, Date refundDate)`	Reembolsa un pago procesado, total o parcialmente, y crea una transacción de reembolso
`syncTransaction(Id transactionId)`	Vuelve a leer una transacción en Payload
`syncPayOrderTransactions(Id payOrderId)`	Lee todas las transacciones que Payload tiene para la orden; actualiza y crea según haga falta

Dos firmas antiguas, voidTransaction(Id) y refundTransaction(Id, Decimal, String), todavía compilan pero lanzan "This method is deprecated. Please follow the documentation for updated method details." Usa las completas.

`rpay.PayMethodWrapper`

Los datos de tarjeta o de banco para createPayMethod y processPayOrder:

Campo	Tarjeta	Cuenta bancaria
`methodType`	`card`	`bank_account`
`cardNumber`, `cardHolderName`, `cardCVV`, `cardExpiry` (MM/YY), `cardType`	✓
`accountName`, `accountNumber`, `routingNumber` (9 dígitos), `accountType`, `accountClass`, `accountCurrency`		✓
`postalCode`	✓	✓

Estos valores pasan por tu Apex hacia Payload y nunca se guardan; consulta Seguridad y datos de tarjetas. No los registres en logs, no los guardes en campos ni los pongas en instrucciones de depuración.

`rpay.TransactionResult`

Campo	Significado
`isSuccess`	Si la operación tuvo éxito
`error_message`	El motivo cuando no lo tuvo
`payorder_name`, `payorder_sfid`	El número y el Id de la orden
`transaction_id`, `transaction_ref`, `transaction_sfid`, `transaction_obj`	El identificador y la referencia de la transacción en Payload, y el registro Pay Transaction
`customer_id`, `customer`	El identificador de cliente de Payload y el registro Pay Customer
`pay_method_id`, `pay_method_description`, `isDefaultMethod`, `card_name`, `card_last4`, `card_brand`, `card_type`, `card_exp_month`, `card_exp_year`	El token y los datos descriptivos del método registrado

Algunos campos más (identification_number, identification_type, external_url, el grupo three_d_secure_mode) existen para uso futuro y no se completan en esta versión.

Ejemplo: procesar una orden con un método guardado

// La Pay Order existe, es Immediate, no está procesada y ya tiene un Pay Method activo.
rpay.TransactionResult r = rpay.PayAPIGlobal.processPayOrder(payOrderId, null);
if (r.isSuccess) {
    System.debug('Processed ' + r.payorder_name + ' as ' + r.transaction_ref);
} else {
    System.debug('Failed: ' + r.error_message);   // se guardó una Pay Transaction fallida bajo la orden
}

Ejemplo: registrar una cuenta bancaria para un proveedor

rpay.PayMethodWrapper w = new rpay.PayMethodWrapper();
w.methodType      = 'bank_account';
w.accountName     = 'Harbor Maintenance LLC';
w.accountNumber   = accountNumberFromYourSecureInput;   // nunca lo escribas en el código ni lo registres
w.routingNumber   = '021000021';
w.accountType     = 'checking';
w.accountClass    = 'business';
w.accountCurrency = 'USD';
w.postalCode      = '33602';

// payMethodId es un registro Pay Method creado con Pay Customer, Pay Profile,
// Pay Method Type = bank_account y Transfer Type = receive-only (desembolso).
rpay.TransactionResult r = rpay.PayAPIGlobal.createPayMethod(payMethodId, w);

Reglas que también se aplican a las llamadas de la API

Las mismas validaciones que en las pantallas: el perfil y la cuenta deben estar activos, el cliente, la cuenta y el método deben permitir el tipo de transferencia y el tipo de método, el usuario que ejecuta el código debe tener permitida la dirección, y una orden procesada no se puede volver a procesar. Las infracciones vuelven en error_message.
Las comisiones por conveniencia se calculan al guardar la orden, a partir de los Fee Setups de la cuenta; define Zero Convenience Fee o Convenience Fee Override en la orden antes de procesarla si hace falta.
Los métodos llaman a Payload de a un registro por vez. Haz los bucles de tu código con cuidado por los límites de llamadas externas, o pasa el trabajo masivo a un batch.
processPayOrder con details registra el método antes de cobrar, así que una tarjeta registrada de esta forma se conserva para reutilizarla salvo que desmarques Keep Active después.

La clase del programador

rpay.SchedulePayOrderJob es el trabajo diario de pagos recurrentes. Es programable y tiene dos propiedades que se pueden definir, processDate (hoy de forma predeterminada) y batchSize (50 de forma predeterminada); consulta Programar el trabajo diario de pagos recurrentes.

Errores que debes evitar

Error	Qué ocurre	Solución
Llamar a la API después de un DML en la misma transacción	Excepción de llamada externa	Llama desde un contexto asíncrono, o antes de cualquier DML
Pasar datos de tarjeta de una fuente no confiable sin validarlos	Payload los rechaza; peor aún, podrías registrarlos	Valida y nunca registres
Esperar que `processPayOrder` cree la orden	Procesa una Pay Order existente	Inserta primero la orden
Usar las firmas obsoletas de anulación o reembolso	Una excepción	Usa las firmas con fecha
Ejecutar como un usuario sin el conjunto de permisos	Errores de acceso	Asigna REDA Pay - Admin User al usuario de integración

Preguntas frecuentes

No una de REDA Pay. Expón los métodos globales mediante tu propia clase Apex REST si un sistema externo los necesita, y protégela como corresponde.

Crea los registros con una carga de datos y luego llama a createPayCustomer y createPayMethod desde un batch, un registro por ejecución, dentro de los límites de frecuencia de Payload.

No. Se ejecuta como el usuario actual, con las mismas comprobaciones de acceso que las pantallas.