API Apex para desenvolvedores
Tudo o que as telas do REDA Pay fazem também está disponível para o Apex da sua organização por meio de uma classe global. Use-a quando um fluxo não basta: uma página de pagamento personalizada, um script de migração que registra clientes existentes na Payload, uma integração que precisa processar uma ordem e ler o resultado de forma síncrona.
- Você é um desenvolvedor Salesforce com a permissão Author Apex, trabalhando em um sandbox contra o ambiente de teste da Payload.
- O usuário em execução precisa do conjunto de permissões do REDA Pay para a operação (Admin User para operações de configuração; Transaction Manager para cancelamento e reembolso) e, para desembolsos, do REDA Pay - Enable Disbursements.
- Todo método faz uma chamada à Payload. Chame-os a partir de um contexto que permita chamadas externas (um método future, queueable ou batch, ou um controlador sem trabalho pendente não confirmado).
A classe
Todos os métodos são estáticos em rpay.PayAPIGlobal e devolvem um rpay.TransactionResult.
| Método | O que faz |
|---|---|
createPayCustomer(Id payCustomerId) | Registra o Pay Customer na Payload e guarda o identificador de cliente |
updatePayCustomer(Id payCustomerId) | Envia à Payload o nome, o e-mail e o telefone do cliente |
createPayMethod(Id payMethodId, rpay.PayMethodWrapper details) | Registra um cartão ou uma conta bancária para um registro Pay Method existente e guarda o token e os dados descritivos |
deletePayMethod(Id payMethodId) | Remove o método na Payload; o registro fica, marcado como excluído |
processPayOrder(Id payOrderId, rpay.PayMethodWrapper details) | Processa uma ordem Immediate. Passe details para registrar um cartão ou uma conta novos no caminho, ou null para usar o Pay Method registrado da ordem |
voidTransaction(Id transactionId, Date voidedDate, String voidingReason) | Cancela uma transação processada e não liquidada |
refundTransaction(Id transactionId, Decimal refundAmount, String description, Date refundDate) | Reembolsa um pagamento processado, total ou parcialmente, criando uma transação de reembolso |
syncTransaction(Id transactionId) | Relê uma transação na Payload |
syncPayOrderTransactions(Id payOrderId) | Lê todas as transações que a Payload tem para a ordem; atualiza e cria conforme necessário |
Duas assinaturas mais antigas, voidTransaction(Id) e refundTransaction(Id, Decimal, String), ainda compilam, mas lançam "This method is deprecated. Please follow the documentation for updated method details." Use as completas.
rpay.PayMethodWrapper
Os dados do cartão ou do banco para createPayMethod e processPayOrder:
| Campo | Cartão | Conta bancária |
|---|---|---|
methodType | card | bank_account |
cardNumber, cardHolderName, cardCVV, cardExpiry (MM/YY), cardType | ✓ | |
accountName, accountNumber, routingNumber (9 dígitos), accountType, accountClass, accountCurrency | ✓ | |
postalCode | ✓ | ✓ |
Esses valores passam pelo seu Apex até a Payload e nunca são armazenados; consulte Segurança e dados de cartão. Não os registre em log, não os guarde em campos e não os coloque em instruções de depuração.
rpay.TransactionResult
| Campo | Significado |
|---|---|
isSuccess | Se a operação deu certo |
error_message | O motivo, quando não deu |
payorder_name, payorder_sfid | O número e o Id da ordem |
transaction_id, transaction_ref, transaction_sfid, transaction_obj | O identificador e a referência da transação na Payload, e o registro Pay Transaction |
customer_id, customer | O identificador de cliente da Payload e o registro Pay Customer |
pay_method_id, pay_method_description, isDefaultMethod, card_name, card_last4, card_brand, card_type, card_exp_month, card_exp_year | O token e os dados descritivos do método registrado |
Alguns campos adicionais (identification_number, identification_type, external_url, o grupo three_d_secure_mode) existem para uso futuro e não são preenchidos nesta versão.
Exemplo: processar uma ordem com um método salvo
// A Pay Order existe, é Immediate, não foi processada e já tem um Pay Method ativo.
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); // uma Pay Transaction com falha foi salva abaixo da ordem
}Exemplo: registrar uma conta bancária para um fornecedor
rpay.PayMethodWrapper w = new rpay.PayMethodWrapper();
w.methodType = 'bank_account';
w.accountName = 'Harbor Maintenance LLC';
w.accountNumber = accountNumberFromYourSecureInput; // nunca escreva isto no código nem em log
w.routingNumber = '021000021';
w.accountType = 'checking';
w.accountClass = 'business';
w.accountCurrency = 'USD';
w.postalCode = '33602';
// payMethodId é um registro Pay Method criado com Pay Customer, Pay Profile,
// Pay Method Type = bank_account e Transfer Type = receive-only (desembolso).
rpay.TransactionResult r = rpay.PayAPIGlobal.createPayMethod(payMethodId, w);Regras que também valem para as chamadas à API
- As mesmas validações das telas: o perfil e a conta precisam estar ativos, o cliente, a conta e o método precisam permitir o tipo de transferência e o tipo de método, o usuário em execução precisa ter permissão para a direção, e uma ordem processada não pode ser processada de novo. As violações voltam em
error_message. - As taxas de conveniência são calculadas quando a ordem é salva, a partir dos Fee Setups da conta; defina Zero Convenience Fee ou Convenience Fee Override na ordem antes de processar, se necessário.
- Os métodos chamam a Payload um registro de cada vez. Faça laços no seu código com cuidado com os limites de chamadas externas, ou passe o trabalho em massa para um batch.
processPayOrdercomdetailsregistra o método antes de cobrar, então um cartão registrado assim fica guardado para reutilização, a menos que você desmarque Keep Active depois.
A classe agendadora
rpay.SchedulePayOrderJob é o trabalho diário de pagamentos recorrentes. Ela pode ser agendada e tem duas propriedades configuráveis, processDate (padrão: hoje) e batchSize (padrão: 50); consulte Agendar o trabalho diário de pagamentos recorrentes.
Erros comuns a evitar
| Erro | O que acontece | Solução |
|---|---|---|
| Chamar a API depois de uma DML na mesma transação | Exceção de chamada externa | Chame a partir de um contexto assíncrono, ou antes de qualquer DML |
| Passar dados de cartão vindos de uma origem não confiável sem validação | A Payload os recusa; pior, você pode registrá-los em log | Valide, nunca registre em log |
Esperar que processPayOrder crie a ordem | Ele processa uma Pay Order existente | Insira a ordem primeiro |
| Usar as assinaturas obsoletas de cancelamento/reembolso | Uma exceção | Use as assinaturas com data |
| Executar como um usuário sem o conjunto de permissões | Erros de acesso | Atribua o REDA Pay - Admin User ao usuário da integração |
Perguntas frequentes
Não uma do REDA Pay. Exponha os métodos globais por meio da sua própria classe Apex REST se um sistema externo precisar deles, e proteja-a de acordo.
Crie os registros com uma carga de dados e depois chame createPayCustomer e createPayMethod a partir de um batch, um registro por execução, dentro dos limites de taxa da Payload.
Não. Ela roda como o usuário atual, com as mesmas verificações de acesso das telas.