Esta página cobre todos os requisitos de dados para pagamentos em USD para a China via CFXPS (China Foreign Exchange Payment System): as identidades que você cria para o beneficiário e o ordenante, o instrumento financeiro que guarda os dados da conta do beneficiário e os campos em nível de transação enviados com cada pagamento.
Os requisitos de identidade, de instrumento financeiro e de nome e endereço se aplicam a todo pagamento em USD para a China. Os campos em nível de transação mais abaixo se aplicam apenas aos casos de uso indicados em cada campo.
Para localizar o código SWIFT/BIC do banco de destino, use a consulta de Códigos bancários.
Analise estas limitações antes de enviar neste corredor e oriente seus clientes conforme necessário. Todas as quatro são conhecidas e acompanhadas, e ainda não há datas de correção confirmadas.
- Alguns bancos de beneficiários são compatíveis apenas com os casos de uso B2B e B2B2B. Escolher um deles para qualquer outro caso de uso não é rejeitado na criação do pagamento. O pagamento segue o roteamento mesmo assim e pode falhar cerca de 4 a 5 dias úteis depois, com um erro genérico. A consulta Códigos bancários ainda não mostra com quais casos de uso cada banco é compatível; o suporte por banco está sendo confirmado e será adicionado lá.
- Os valores SWIFT/BIC do beneficiário não são validados na criação do pagamento. Um BIC inválido, ou um BIC de agência em vez de um BIC de matriz, é aceito e falha da mesma forma.
- Os comprimentos máximos exibidos no Payments Direct UI ao criar um beneficiário pessoa física podem não corresponder aos limites documentados nesta página. Os limites desta página são os que o parceiro pagador aplica. A API não os impõe, então um valor que os ultrapasse é aceito na criação e falha depois, no payout.
- Envie um pagamento de teste de baixo valor para cada caso de uso antes de aumentar o volume. O penny testing neste corredor é limitado pela regulamentação local, então a cobertura da própria Ripple ainda está em andamento.
As tabelas de identidade e de instrumento financeiro nesta página listam apenas os campos que CN_CFXPS exige, extraídos do schema PII v3. Identidades e instrumentos financeiros aceitam outros campos opcionais. Para o conjunto completo, consulte Identidades do pagamento e Instrumentos financeiros, ou use o Utilitário de schema de payload.
Vale entender três aspectos deste corredor antes de integrar.
Nos pagamentos em USD à China, COMPLETED significa que os recursos chegaram ao banco do beneficiário. Isso nem sempre significa que a conta do beneficiário foi creditada.
Na maioria dos casos, o banco do beneficiário primeiro analisa o pagamento para fins de compliance, porque os controles cambiais chineses exigem análise de todo pagamento em USD recebido, independentemente do valor. O banco entra em contato diretamente com o beneficiário para obter documentação comprobatória, como nota fiscal, comprovante de embarque ou alfandegário, contrato de trabalho ou comprovante de vínculo. Em uma minoria dos casos, ele credita a conta imediatamente. Não é possível saber de antemão o que vai acontecer.
Esse processo está fora do controle da Ripple e não há SLA aplicável. O crédito costuma levar vários dias úteis e pode levar semanas se o banco escalar para due diligence reforçada. O prazo depende de quando o beneficiário fornece documentação satisfatória. Alinhe as expectativas com seus beneficiários de acordo com isso e não trate COMPLETED como comprovante de recebimento.
Depois que um pagamento é iniciado, não é possível cancelá-lo, alterá-lo nem solicitar estorno ou devolução. Apenas o banco do beneficiário pode iniciar uma devolução, o que ocorre quando o pagamento não passa na análise de compliance.
Um pagamento devolvido pode valer menos do que o valor enviado, porque o banco que devolve pode descontar uma tarifa de processamento. As tarifas variam por banco e agência, então considere essa diferença ao conciliar devoluções.
Como um pagamento não pode ser corrigido após o envio, confira os dados do beneficiário antes de enviar. Valores enviados a um beneficiário não pretendido geralmente não são recuperáveis, e dados incorretos ou incompletos podem atrasar um pagamento ou fazer com que ele se perca.
O payment rail CFXPS funciona apenas em dias úteis, de segunda a sexta-feira, excluindo feriados nacionais chineses. O horário de corte é 17h00 CST e varia conforme o banco, então confirme o horário de corte aplicável ao banco do seu beneficiário. Pagamentos enviados após esse horário são processados no próximo dia útil.
Enviar antes do horário de corte não garante conclusão no mesmo dia. O horário de corte determina quando um pagamento entra em processamento, não quando ele termina. Pagamentos encaminhados para uma fila de validação manual podem levar mais um dia útil ou mais. A análise de compliance do banco do beneficiário acrescenta ainda mais tempo além disso.
Crie a identidade do beneficiário antes do instrumento financeiro e faça referência a ela ao criar o pagamento. Consulte Criar e gerenciar identidades para o fluxo da API.
Os campos obrigatórios dependem de o beneficiário ser uma empresa ou uma pessoa física.
Aplica-se aos casos de uso B2B, B2B2B e C2B2B. Envie uma identidade business.
| Campo | Obrigatório | Tipo | Restrições |
|---|---|---|---|
businessName | Obrigatório | STRING | De 1 a 140 caracteres aceitos pela API. O CFXPS trunca o nome e o endereço combinados acima do seu próprio limite, então mantenha este campo em 60 caracteres. Consulte Limites de comprimento dos campos de nome e endereço. |
address.streetAddress | Obrigatório | ARRAY de STRING | Uma ou mais linhas de endereço em formato livre. Envie exatamente uma linha para este corredor; consulte Limites de comprimento dos campos de nome e endereço. |
address.city | Obrigatório | STRING | De 1 a 140 caracteres. Apenas letras, espaços e . ' -, portanto sem dígitos. |
address.stateOrProvince | Obrigatório | STRING | De 1 a 140 caracteres. Letras, dígitos, espaços e . ' -. |
address.postalCode | Obrigatório | STRING | De 3 a 15 caracteres. Se nenhum código postal se aplicar ao endereço, envie 000000. |
address.country | Obrigatório | STRING | Código de país ISO 3166-1 alfa-2, com duas letras maiúsculas. |
Aplica-se aos casos de uso B2C, B2B2C e C2B2C. Envie uma identidade individual.
| Campo | Obrigatório | Tipo | Restrições |
|---|---|---|---|
firstName | Obrigatório | STRING | De 1 a 140 caracteres. Apenas letras, espaços e . ' -, portanto sem dígitos. |
lastName | Obrigatório | STRING | De 1 a 140 caracteres. Apenas letras, espaços e . ' -, portanto sem dígitos. |
address.streetAddress | Obrigatório | ARRAY de STRING | Uma ou mais linhas de endereço em formato livre. Envie exatamente uma linha para este corredor; consulte Limites de comprimento dos campos de nome e endereço. |
address.city | Obrigatório | STRING | De 1 a 140 caracteres. Apenas letras, espaços e . ' -, portanto sem dígitos. |
address.stateOrProvince | Obrigatório | STRING | De 1 a 140 caracteres. Letras, dígitos, espaços e . ' -. |
address.postalCode | Obrigatório | STRING | De 3 a 15 caracteres. Se nenhum código postal se aplicar ao endereço, envie 000000. |
address.country | Obrigatório | STRING | Código de país ISO 3166-1 alfa-2, com duas letras maiúsculas. |
Defina financialInstrumentType: CN_CFXPS e currency: USD. Forneça os campos a seguir no objeto do payment rail cnCfxps. Consulte Criar e gerenciar instrumentos financeiros para o fluxo da API.
| Campo | Obrigatório | Tipo | Restrições |
|---|---|---|---|
swiftCode | Obrigatório | STRING | 8 ou 11 caracteres, correspondendo a /^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$/. Use a consulta Códigos bancários e selecione China para encontrá-lo. |
bankName | Obrigatório | STRING | De 2 a 140 caracteres. O nome do banco do beneficiário, correspondente ao swiftCode acima. |
accountNumber | Obrigatório | STRING | De 1 a 34 caracteres, apenas letras e dígitos. |
accountHolderName | Obrigatório | STRING | De 1 a 140 caracteres, em inglês. A API e o CFXPS aceitam pontuações ligeiramente diferentes neste campo, então use apenas letras, dígitos, espaços e . , ' / ( ) -, que ambos permitem. A API também aceita &; o CFXPS não. |
A identidade do ordenante representa a parte que financia o pagamento. Consulte Criar e gerenciar identidades para o fluxo da API.
Envie uma identidade business.
| Campo | Obrigatório | Tipo | Restrições |
|---|---|---|---|
businessName | Obrigatório | STRING | De 1 a 140 caracteres aceitos pela API. Mantenha este campo em 60 caracteres para o CFXPS. Consulte Limites de comprimento dos campos de nome e endereço. |
address.streetAddress | Obrigatório | ARRAY de STRING | Uma ou mais linhas de endereço em formato livre. Envie exatamente uma linha para este corredor; consulte Limites de comprimento dos campos de nome e endereço. |
address.city | Obrigatório | STRING | De 1 a 140 caracteres. Apenas letras, espaços e . ' -, portanto sem dígitos. |
address.stateOrProvince | Obrigatório | STRING | De 1 a 140 caracteres. Letras, dígitos, espaços e . ' -. |
address.postalCode | Obrigatório | STRING | De 3 a 15 caracteres. Se nenhum código postal se aplicar ao endereço, envie 000000. |
address.country | Obrigatório | STRING | Código de país ISO 3166-1 alfa-2, com duas letras maiúsculas. |
registration[].number | Obrigatório | STRING | O identificador exclusivo da organização. De 3 a 35 caracteres. Deve corresponder a ^(?![ .'-\/])(?!.*[ .'-\/]{2})([A-Za-z0-9 .'-\/]+)(?<![ .'-\/])\/?$. |
registration[].type | Obrigatório | STRING | Um destes: INCORPORATION_CERTIFICATE, TAX_ID. |
originatorAccountNumber | Obrigatório | STRING | Consulte Número da conta do ordenante abaixo. |
Envie uma identidade individual.
| Campo | Obrigatório | Tipo | Restrições |
|---|---|---|---|
firstName | Obrigatório | STRING | De 1 a 140 caracteres. Apenas letras, espaços e . ' -, portanto sem dígitos. |
lastName | Obrigatório | STRING | De 1 a 140 caracteres. Apenas letras, espaços e . ' -, portanto sem dígitos. |
address.streetAddress | Obrigatório | ARRAY de STRING | Uma ou mais linhas de endereço em formato livre. Envie exatamente uma linha para este corredor; consulte Limites de comprimento dos campos de nome e endereço. |
address.city | Obrigatório | STRING | De 1 a 140 caracteres. Apenas letras, espaços e . ' -, portanto sem dígitos. |
address.stateOrProvince | Obrigatório | STRING | De 1 a 140 caracteres. Letras, dígitos, espaços e . ' -. |
address.postalCode | Obrigatório | STRING | De 3 a 15 caracteres. Se nenhum código postal se aplicar ao endereço, envie 000000. |
address.country | Obrigatório | STRING | Código de país ISO 3166-1 alfa-2, com duas letras maiúsculas. |
originatorAccountNumber | Obrigatório | STRING | Consulte Número da conta do ordenante abaixo. |
O CFXPS exige o número da conta do ordenante em todo pagamento em USD à China. Envie-o no campo originatorAccountNumber da identidade ORIGINATOR. A Ripple repassa esse valor ao parceiro pagador.
O campo originatorAccountNumber é obrigatório sempre que você valida uma identidade de ordenante contra CN_CFXPS. Criar ou atualizar a identidade sem ele falha com 400 Bad Request (USR_111). O valor precisa ser um número de conta ou identificador de cliente real, e não uma referência arbitrária como um UUID gerado aleatoriamente:
| Se o ordenante for | Envie |
|---|---|
| Um banco ou outra instituição financeira | O número da conta bancária do ordenante |
| Um prestador de serviços de pagamento | O seu identificador de cliente para o ordenante, em formato numérico ou semelhante a um número |
Dê preferência a dígitos. O banco do beneficiário aplica a sua própria validação a esse valor, à parte dos limites de caracteres e de comprimento abaixo, e pode rejeitar um valor que não se pareça com um número de conta.
Isso é mais relevante se você for um prestador de serviços de pagamento enviando o seu próprio identificador de cliente. Uma referência interna em um formato claramente diferente de uma conta, como um ID de registro de CRM que mistura letras e pontuação, pode ser rejeitada pelo banco do beneficiário mesmo que a Ripple a aceite e o pagamento chegue ao corredor. Quando puder escolher, envie um identificador numérico de cliente ou de conta.
Nos pagamentos em USD à China, o campo originatorAccountNumber precisa:
- Ter no máximo 34 caracteres.
- Corresponder a
/^[A-Za-z0-9/?:().,'+ -]+$/, o mesmo conjunto de caracteres dos campos de nome e endereço descritos abaixo.
A API aceita qualquer string neste campo por definição, portanto nenhum dos dois limites é validado na criação da identidade. Um valor que viole qualquer um deles falha no momento do payout. Um UUID padrão de 36 caracteres excede o limite de comprimento, e é por isso que um identificador gerado automaticamente não pode ser usado aqui.
O campo originatorAccountNumber também precisa ser único entre todas as identidades ACTIVE da sua organização. Criar ou atualizar uma segunda identidade ativa com o mesmo valor falha com 409 Conflict (USR_122). A unicidade abrange os dois papéis, portanto uma identidade de beneficiário que já tenha um valor impede que um ordenante posterior o utilize. Cada ordenante precisa do seu próprio valor: não é possível reutilizar um único número de conta compartilhado em várias identidades ativas.
originatorAccountNumber e internalId são campos diferentes, e a diferença importa aqui. Se você deixar originatorAccountNumber vazio, a Ripple envia internalId ao parceiro pagador no lugar dele, como número da conta do ordenante.
Isso raramente é o que você quer. internalId é a sua própria chave de referência e, no Payments Direct UI, é gerado automaticamente como um UUID que você nunca vê. Um UUID de 36 caracteres também excede o limite de 34 caracteres acima.
Envie o número da conta em originatorAccountNumber. Não o envie em internalId, que tem sua própria regra de unicidade.
Para o comportamento geral de internalId, incluindo como tratar respostas 409, consulte Identidades do pagamento.
Inclua CN_CFXPS em validatePayoutRails ao criar ou atualizar a identidade do ordenante. Isso faz a Ripple verificar os campos obrigatórios do corredor nesse momento, de modo que a ausência de originatorAccountNumber falha imediatamente com 400 Bad Request (USR_111).
Se você omitir o payment rail, nada verifica o campo na criação da identidade. O primeiro sinal de problema é a rejeição do pagamento. Consulte Validando identidades para payment rails específicos.
Um pagamento em USD para a China é rejeitado na criação quando o originatorAccountNumber do ordenante está ausente ou contém um UUID. POST /v3/payments retorna 400 Bad Request antes de o pagamento alcançar um estado de pagamento, portanto nenhum valor é reservado ou debitado e não há o que estornar.
| Código | Causa | Mensagem |
|---|---|---|
USR_090 | O campo está ausente ou vazio | O campo 'originator.originatorAccountNumber' é obrigatório, mas está ausente ou vazio. Forneça o número da conta do cliente ordenante (DbtrAcct.Id.Othr.Id), e não um UUID. |
USR_068 | O campo contém um UUID | Erro de validação do valor do campo da requisição: originator.originatorAccountNumber. Mensagem de erro: não pode ser um UUID — forneça o número da conta do cliente ordenante. Tente novamente com um valor de entrada válido. |
Para resolver, adicione um número de conta válido à identidade do ordenante e crie o pagamento novamente.
Os valores de nome e endereço nos pagamentos em USD à China via CFXPS precisam usar letras (A-Z, a-z), dígitos (0-9), espaços e os sinais de pontuação / ? : ( ) . , ' + -. Qualquer outro caractere faz com que o payout seja rejeitado. Caracteres chineses e outros sistemas de escrita não latinos não são compatíveis, assim como sinais de pontuação comuns fora do conjunto acima, como &, #, " e _.
Mantenha os valores de cada campo abaixo o mais concisos possível. Para cada parte, o nome e o endereço postal combinados têm um máximo total de 139 caracteres. Esse total se aplica separadamente ao beneficiário e ao ordenante, e os limites por campo abaixo são uma distribuição dele.
Nenhum desses dois limites é validado pela API. Ambos são aplicados pelo CFXPS depois que o pagamento é enviado, e eles se comportam de forma diferente:
- Um caractere não compatível rejeita o pagamento. O CFXPS o devolve, então você fica sabendo.
- Um nome ou endereço longo demais é truncado, não rejeitado. O CFXPS encurta o nome e o endereço combinados para caber e encaminha o pagamento. Nada avisa que isso aconteceu, e o banco do beneficiário pode devolver ou encaminhar incorretamente um pagamento que chega com o nome ou o endereço encurtado.
O truncamento é o mais prejudicial dos dois, porque o dinheiro se movimenta com dados incorretos. Trate os limites de comprimento abaixo como requisitos rígidos, ainda que nada os imponha na entrada.
Todos os campos de nome e endereço precisam usar o conjunto de caracteres descrito acima, expresso por esta expressão regular:
/^[A-Za-z0-9/?:().,'+ -]+$/
A API aplica a sua própria validação, separada, a esses campos, e em alguns deles ela é mais rígida que o CFXPS. Nomes de pessoas e cidade, por exemplo, rejeitam dígitos. Assim, um valor pode atender ao conjunto de caracteres acima e ainda ser rejeitado pela API com um 400, e um valor que a API aceita ainda pode ser rejeitado pelo CFXPS. Use o Utilitário de schema de payload com CN_CFXPS selecionado para ver as duas restrições aplicadas em conjunto a um determinado campo.
| Campo | Aplica-se a | Comprimento máximo |
|---|---|---|
businessName | Beneficiário e ordenante (empresa) | 60 |
firstName, lastName | Beneficiário e ordenante (pessoa física) | 15 cada |
address.city | Beneficiário | 16 |
address.country | Beneficiário e ordenante | 2 |
| Linha de endereço combinada | Beneficiário (empresa) | 61 |
| Linha de endereço combinada | Beneficiário (pessoa física) | 76 |
| Linha de endereço combinada | Ordenante (empresa) | 77 |
| Linha de endereço combinada | Ordenante (pessoa física) | 92 |
Antes de enviar um pagamento, a Ripple combina vários dos campos de endereço que você informa na linha de endereço, separados por , . Os limites acima se aplicam ao resultado combinado, não a address.streetAddress isoladamente.
Para um beneficiário, a linha combinada é:
streetAddress + stateOrProvince + postalCode
portanto, os valores devem atender a:
len(streetAddress) + len(stateOrProvince) + len(postalCode) + 4 <= 61 (empresa) ou <= 76 (pessoa física)
Para um ordenante, o campo city também é incorporado, porque o CFXPS não tem um campo de cidade separado para o ordenante:
streetAddress + city + stateOrProvince + postalCode
portanto, os valores devem atender a:
len(streetAddress) + len(city) + len(stateOrProvince) + len(postalCode) + 6 <= 77 (empresa) ou <= 92 (pessoa física)
As constantes somadas são os separadores: 2 caracteres para cada junção.
O schema também declara um limite de 70 caracteres para cada entrada de address.streetAddress, mas a API não o impõe. Um valor maior é aceito e armazenado por completo. Quando um limite combinado acima for maior que 70, o limite por entrada é o mais restritivo dos dois e é o que deve orientar o design. Assim como os limites combinados, nada o verifica na criação da identidade, então trate ambos como requisitos que você mesmo precisa cumprir.
Os campos stateOrProvince e postalCode são obrigatórios em toda identidade, portanto reserve espaço para eles mesmo que não tenham limite individual neste corredor.
O campo address.streetAddress é um array, portanto a API aceita mais de uma entrada. Somente a primeira entrada é entregue neste corredor. Qualquer conteúdo em uma segunda entrada ou posterior é descartado em trânsito.
Isso é pior do que perder uma linha de endereço. O estado ou província e o código postal são anexados à última entrada, de modo que, com duas ou mais entradas, eles são anexados a uma linha que nunca é entregue, e o banco do beneficiário recebe um endereço sem estado e sem código postal. É por isso que a interface da Ripple envia uma única linha, e quem envia pela API deve fazer o mesmo.
Coloque todo o endereço na primeira entrada e não envie outras.
Os limites acima são uma distribuição do total de 139 caracteres de uma parte. Para um beneficiário empresa, eles o utilizam por completo: razão social (60) + linha de endereço combinada (61) + cidade (16) + país (2) = 139. Para um ordenante empresa: razão social (60) + linha de endereço combinada (77) + país (2) = 139.
Para pessoas físicas, a distribuição reserva 15 caracteres para um nome do meio, que esta API não expõe, de modo que os campos que você pode enviar chegam a 124 em vez de 139. Os 15 caracteres restantes não ficam disponíveis para outros campos. Usar menos caracteres em um campo nunca aumenta o máximo permitido em outro.
| Campo | Descrição | Obrigatório | Tipo | Restrições |
|---|---|---|---|---|
purposeCode | Finalidade do pagamento | Obrigatório para B2B e B2B2B | ENUM | Consulte os valores válidos abaixo. Não obrigatório para outros casos de uso |
O campo purposeCode é obrigatório quando tanto o ordenante quanto o beneficiário são empresas, ou seja, nos casos de uso B2B e B2B2B. Ele não é obrigatório para B2C, B2B2C, C2B2B ou C2B2C, e as rotas que atendem a esses casos de uso não o consomem.
| Código | Descrição |
|---|---|
GDDS | Compra ou venda de bens |
SCVE | Compra ou venda de serviços |