Princípios Básicos da API SOAP do PayPal

A API do PayPal SOAP é baseada em padrões abertos conhecidos coletivamente como serviços da Web, que incluem o SOAP (Simple Object Access Protocol), o WSDL (Web Services Definition Language) e o XSD (XML Schema Definition language). Uma ampla variedade de ferramentas de desenvolvimento em diversas plataformas oferece suporte a serviços da Web.

Como muitos serviços da Web, o PayPal SOAP é uma combinação de esquemas do lado do cliente e do lado do servidor, servidores de hardware e software e serviços principais.

Diagrama de alto nível do PayPal SOAP

Em um modelo de processamento orientado a objetos, a interface para solicitações / respostas SOAP é um objeto na linguagem de programação nativa do seu aplicativo. Seu cliente SOAP de terceiros gera interfaces de objeto de negócios e stubs de rede dos arquivos WSDL e XSD fornecidos pelo PayPal que especificam a estrutura de mensagens do PayPal SOAP, seu conteúdo e as ligações de serviço da API do PayPal. Um aplicativo de negócios trabalha com dados na forma de propriedades do objeto para enviar e receber dados chamando métodos de objeto. O cliente SOAP manipula os detalhes da criação da solicitação SOAP, enviando-a ao serviço do PayPal e convertendo a resposta de volta para um objeto.

Definições de esquema do PayPal WSDL / XSD

O esquema de Serviços da Web do PayPal e seus componentes básicos e base do eBay Business Language (eBL) são necessários para o desenvolvimento de aplicativos com a API de serviços da Web do PayPal. A seguir estão os locais dos arquivos WSDL e XSD.

Localização dos arquivos PayPal WSDL e XSD
Desenvolvimento e teste com a sandbox do PayPal
Esquema do PayPal https://www.sandbox.paypal.com/wsdl/PayPalSvc.wsdl
Componentes básicos e componentes do eBL https://www.sandbox.paypal.com/wsdl/eBLBaseComponents.xsd 
https://www.sandbox.paypal.com/wsdl/CoreComponentTypes.xsd
Produção com a API do PayPal ao vivo
Esquema do PayPal https://www.paypal.com/wsdl/PayPalSvc.wsdl
Componentes básicos e componentes do eBL https://www.paypal.com/wsdl/eBLBaseComponents.xsd 
https://www.paypal.com/wsdl/CoreComponentTypes.xsd

Definições da API do SOAP do PayPal

A API do PayPal para SOAP inclui definições de API individuais para funções comerciais específicas. Como base, a API depende dos componentes básicos e básicos da eBay Business Language (eBL). As principais estruturas do eBL AbstractRequestTypeAbstractResponseTypesão a base da solicitação e resposta do SOAP de cada API do PayPal. AbstractResponseTypetambém é a estrutura para mensagens de erro comuns em todas as APIs do PayPal.

O PayPal tomou algumas decisões de design de esquema que podem afetar como os negócios projetam seus próprios aplicativos.

  • Enumerações – Enumerações são definidas diretamente no esquema da API do PayPal.
  • Informações de solução de problemas – A API do PayPal retorna informações sobre elementos que acionam erros.
  • Compatibilidade retroativa – A API do PayPal é versionada para que os aplicativos de negócios sejam compatíveis com versões anteriores quando novos elementos são introduzidos no esquema do lado do servidor.

Nota: O eBL define muitas estruturas específicas para leilões de processamento. O esquema SOAP do PayPal inclui essas definições para manter a compatibilidade com o SOAP do eBay. O material se concentra apenas nas definições de SOAP pertinentes ao uso da API do PayPal SOAP.

Segurança

O serviço da API SOAP do PayPal é protegido para garantir que apenas membros autorizados do PayPal o usem. Existem quatro níveis de segurança:

  1. Uma API Usernamee uma API obrigatórias Password.
  2. Um terceiro mecanismo de autenticação obrigatório, que é um dos seguintes:
    • Assinatura de solicitação do lado do cliente usando um certificado de API emitido pelo PayPal
    • Solicitar autenticação usando uma assinatura de API incluída na solicitação
  3. Se você estiver chamando a API em nome de um comerciante de terceiros, deverá especificar o endereço de e-mail registrado no PayPal do comerciante de terceiros ou o ID da conta do comerciante (às vezes chamado de ID do pagador) no Subjectcampo.

    Nota: Terceiros podem obter seu ID de comerciante entrando no paypal.com , clicando no ícone do perfil ( Menu Perfil) no canto superior direito da página e selecionando Perfil e configurações no menu Perfil de negócios . (Se o ícone do perfil na parte superior da página não estiver visível, clique em Perfil , que aparece no menu superior quando a guia Minha conta estiver selecionada.) Clique em Informações da minha empresa à esquerda e o ID da conta do comerciante é exibido no lista de itens de perfil à direita.

    Normalmente, um comerciante concede permissões de terceiros a um carrinho de compras, portanto, o carrinho de compras pode chamar a API em nome do comerciante. O comerciante deve ter concedido anteriormente permissão para executar a operação da API.

  4. Transporte de dados TLS (Transport Layer Security). Consulte as diretrizes de segurança das informações do desenvolvedor do PayPal para obter mais informações sobre o TLS.

Uma falha na segurança autenticada em qualquer um desses níveis nega acesso ao serviço da API do PayPal SOAP.

RequesterCredentials SOAP: nome de usuário, senha, assinatura e assunto

Para a segurança de seus negócios, o PayPal deve verificar se os comerciantes ou desenvolvedores de terceiros têm permissão para iniciar uma transação antes de fazer uma. O PayPal autentica cada solicitação. Se a solicitação não puder ser autenticada, uma falha de segurança SOAP será retornada.

No cabeçalho da solicitação SOAP, seu cliente SOAP deve definir os elementos UsernamePasswordpara passar uma combinação de nome de usuário / senha da API. Além disso, você pode definir o Signaturepara especificar sua string de assinatura de API. Se você estiver chamando a API em nome de um comerciante de terceiros, deverá definir o Subjectelemento para especificar o endereço de e-mail de terceiros ou o ID da conta do comerciante (às vezes chamado de ID do pagador).

Nota: Terceiros podem obter seu ID de comerciante entrando no paypal.com , clicando no ícone do perfil ( Menu Perfil) no canto superior direito da página e selecionando Perfil e configurações no menu Perfil de negócios . (Se o ícone do perfil na parte superior da página não estiver visível, clique em Perfil , que aparece no menu superior quando a guia Minha conta estiver selecionada.) Clique em Informações da minha empresa à esquerda e o ID da conta do comerciante é exibido no lista de itens de perfil à direita.

Normalmente, um comerciante concede permissões de terceiros a um carrinho de compras, portanto, o carrinho de compras pode chamar a API em nome do comerciante. O comerciante deve ter concedido anteriormente permissão para executar a operação da API.

O exemplo a seguir mostra parte dos RequesterCredentialselementos.

A maioria desses elementos é necessária para todas as solicitações SOAP.

<SOAP-ENV:Header>
  <RequesterCredentials xmlns="urn:ebay:api:PayPalAPI" xsi:type="ebl:CustomSecurityHeaderType">
  <Credentials xmlns="urn:ebay:apis:eBLBaseComponents" xsi:type="ebl:UserIdPasswordType">
    <Username>API-Username</Username>
    <Password>API-Password</Password>
    <Signature>API-Signature</Signature>
    <Subject>Authorizing-Merchant-Email -or- Authorizing-Merchant-Account-ID</Subject>
  </Credentials>
  </RequesterCredentials>
</SOAP-ENV:Header>
Elementos de autenticação RequesterCredentials no cabeçalho SOAP
Elemento Valor Descrição
Username API-Username Seu nome de usuário da API, que é gerado automaticamente pelo PayPal quando vocêsolicita credenciais de API de certificado ou assinatura para usar a API do PayPal SOAP. Você pode ver esse valor em https://www.paypal.com/ em seu perfil em Acesso à API> Credenciais da API.
Password API-Password Sua senha da API, que você especifica quandosolicita credenciais de API de certificado ou assinatura para usar a API do PayPal SOAP.
Signature API-Signature Sua assinatura de API , se você usar uma em vez de um certificado de API.
Subject Authorizing-Merchant-Email

ou

Authorizing-Merchant-Account-ID

O endereço de e-mail ou ID da conta do comerciante (às vezes chamado de ID do pagador) de um terceiro para quem você está enviando solicitações para a API do PayPal para SOAP. Seu nome de usuário da API deve terrecebido permissão desse terceiro para fazer uma solicitação da API do PayPal em seu nome.

Pontos de extremidade do serviço SOAP

O terminal em serviço que processa suas solicitações SOAP depende do tipo de credenciais da API.

Pontos de extremidade do serviço SOAP
Tipo de credenciais da API Ponto de extremidade de produção ao vivo Ponto de extremidade de teste (sandbox)
Certificado de API https://api.paypal.com/2.0/ https://api.sandbox.paypal.com/2.0/
Assinatura API https://api-3t.paypal.com/2.0/ https://api-3t.sandbox.paypal.com/2.0/

Envelope de pedido SOAP

O diagrama a seguir ilustra o conteúdo de um envelope de solicitação do PayPal SOAP.

Todas as APIs do PayPal são baseadas em duas estruturas principais: AbstractRequestTypeAbstractResponseType.

Diagrama do envelope de solicitação SOAP

Solicitar estrutura

A descrição anotada a seguir da estrutura de solicitação SOAP mostra os elementos requeridos pela API do PayPal SOAP.

Estrutura geral da solicitação SOAP da API do PayPal

1.  <?xml version="1.0" encoding="UTF-8"?>
2.  <SOAP-ENV:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
3.    <SOAP-ENV:Header>
4.      <RequesterCredentials xmlns="urn:ebay:api:PayPalAPI">
5.        <Credentials xmlns="urn:ebay:apis:eBLBaseComponents">
6.          <Username>API-Username</Username>
7.          <Password>API-Password</Password>
8.          <Signature/>
9.          <Subject/>
10.       </Credentials>
11.     </RequesterCredentials>
12.   </SOAP-ENV:Header>
13.   <SOAP-ENV:Body>
14.     <Specific-API-Name-Req xmlns="urn:ebay:api:PayPalAPI">
15.       <Specific-API-Name-Request>
16.         <Version xmlns="urn:ebay:apis:eBLBaseComponents">API-Version</Version>
17.         <Required-Or-Optional-Fields xs:type="Type">Data</Required-Or-Optional-Fields>
18.       </Specific-API-Name-Request>
19.     </Specific-API-Name-Req>
20.   </SOAP-ENV:Body>
21. </SOAP-ENV:Envelope>
Anotação de solicitação SOAP genérica
Linhas Comente
6, 7 Os campos UsernamePasswordsão parte do RequesterCredentialsmecanismo de autenticação de segurança da API SOAP do PayPal que você deve construir para cada cabeçalho de solicitação SOAP. Veja RequesterCredentials para mais informações.
8 Signatureelemento deve incluir sua assinatura de API se esse for o tipo de credencial de API que você está usando.
9 Subjectelemento deve ser incluído ao usar permissões de terceiros (realizando transações em nome de outro comerciante que tenha autorizado você a fazer isso). Passe o ID da conta do comerciante de terceiros autorizador (às vezes chamado de ID do pagador) ou endereço de e-mail.
13 a 20 A solicitação SOAP para cada API do PayPal segue esse padrão de nomenclatura de elemento. O nome específico da API é anexado com Reqe, nesse elemento, o nomeSpecific-API-Name-Reqé aninhado. Cada Specific-API-Name-Requestum tem um correspondente Specific-API-Name-RequestType.
16 O número da versão da API do PayPal SOAP é necessário em cada solicitação SOAP. Este número de versão é o valor de ns:versionem https://www.paypal.com/wsdl/PayPalSvc.wsdl .
17 Para detalhes sobre elementos obrigatórios e opcionais e valores para solicitações específicas, consulte as referências da API .

Estilo da Mensagem SOAP: doc-literal

PayPal usa doc-literalmensagens SOAP, não rpc-encoding. Com doc-literal, uma única chamada de interface de serviço passa um documento XML na solicitação para o servidor da API do PayPal, que responde com uma instância do documento XML.

Estrutura de Resposta

A seguir, uma descrição anotada da estrutura de uma resposta SOAP bem-sucedida da API do PayPal, em que Ack=Success:

1.  <?xml version="1.0"?>
2.  <SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
    xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema"
    xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:cc="urn:ebay:apis:CoreComponentTypes"
    xmlns:wsu="http://schemas.xmlsoap.org/ws/2002/07/utility"
    xmlns:saml="urn:oasis:names:tc:SAML:1.0:assertion"
    xmlns:ds="http://www.w3.org/2000/09/xmldsig#"
    xmlns:wsse="http://schemas.xmlsoap.org/ws/2002/12/secext"
    xmlns:ebl="urn:ebay:apis:eBLBaseComponents"
    xmlns:ns="urn:ebay:api:PayPalAPI">
3.    <SOAP-ENV:Header>
4.      <Security xmlns="http://schemas.xmlsoap.org/ws/2002/12/secext"xsi:type="wsse:SecurityType"/>
5.      <RequesterCredentials xmlns="urn:ebay:api:PayPalAPI" xsi:type="ebl:CustomSecurityHeaderType">
6.        <Credentials xmlns="urn:ebay:apis:eBLBaseComponents" xsi:type="ebl:UserIdPasswordType"/>
7.      </RequesterCredentials>
8.    </SOAP-ENV:Header>
9.    <SOAP-ENV:Body id="_0">
10.     <Specific-API-Operation-Name>-Response xmlns="urn:ebay:api:PayPalAPI">
11.       <Timestamp xmlns="urn:ebay:api:PayPalAPI">DateTime-In-UTC/GMT-Format</TIMESTAMP>
12.       <Ack xmlns="urn:ebay:apis:eBLBaseComponents">Success</Ack>
13.       <Version xmlns="urn:ebay:apis:eBLBaseComponents">API-Version</Version>
14.       <CorrelationId xmlns="urn:ebay:apis:eBLBaseComponents">Correlation-ID</CorrelationID>
15.       <Build xmlns="urn:ebay:apis:eBLBaseComponents">API-Build-Number</Build>
16.       <Elements-For-Specific-API-Response></Elements-For-Specific-API-Response>
17.     </Specific-API-Operation-Name-Response>
18.   </SOAP-ENV:Body>
19. </SOAP-ENV:Envelope>
Anotação de Resposta SOAP Genérica
Linhas Comente
10 a 17 Os elementos de início e fim. Um exemplo de uma operação da API é . Consulte a referência da API NVP / SOAP para obter uma lista completa.Specific-API-Operation-Name-ResponseSetExpressCheckout
11 Cada resposta da API contém uma Timestampdata e hora no formato UTC / GMT.
12 Ackelemento acknowledgement ( ) contém a string Successindicando que a solicitação correspondente foi processada com sucesso. Quando há um erro, ele Acké definido como um valor diferente de Successe o corpo da resposta contém um Errorselemento com informações para ajudá-lo a solucionar a causa do erro. Veja Respostas de erros para mais informações.
14 CorrelationIDelemento contém informações sobre o aplicativo do PayPal que processou a solicitação. Use o valor desse elemento se você precisar solucionar um problema com uma das suas solicitações.
16 As diferentes APIs do PayPal retornam elementos diferentes, dependendo de suas definições de resposta. Para informações detalhadas, consulte as descrições na referência da API .

Nota: Como um campo é definido na estrutura formal de uma resposta da API, isso não significa que o campo seja necessariamente retornado. Os dados são retornados em uma resposta somente se o PayPal registrou dados que correspondem ao campo.

Respostas de erro

Se o Ackvalor não for Success, o pagamento ou ação desejada pode não passar.

Os valores possíveis do Ackcampo de resposta são os seguintes:

  • Success – O pedido foi bem sucedido.
  • SuccessWithWarning – A solicitação foi bem-sucedida, mas um código de erro de aviso também foi retornado.
  • Failure– A solicitação da API falhou. Veja mensagens de erro para detalhes.
  • FailureWithWarning – A solicitação da API falhou e mensagens de aviso adicionais foram retornadas.

Se uma solicitação estiver mal formada ou contiver algum outro erro, o corpo da resposta SOAP conterá um Errorselemento com outros elementos que podem ajudá-lo a solucionar a causa do erro.

A estrutura das mensagens de erro é a seguinte:

O mais importante desses elementos adicionais é o seguinte:

  • ShortMessage
  • LongMessage
  • ErrorCode

Informações adicionais podem aparecer como parte de ErrorParametersType. Por exemplo, se a resposta retornada dentro do ParamIDelemento for ProcessorResponse, o Valueelemento conterá um erro específico do processador de placa de terceiros, como 0091. Os valores definidos no ErrorParametersTypenão são definidos pelo PayPal; em vez disso, eles são passados ​​da fonte.

Nota: o PayPal apenas transmite os valores selecionados em ErrorParametersType.

O exemplo a seguir mostra a resposta de erro se o nome de usuário e a senha da API não corresponderem a um nome de usuário e senha legítimos da API registrados no PayPal.

Exemplo da resposta de erro SOAP: Nome de usuário ou senha inválidos

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV: Envelope [DETAILS NOT SHOWN]>
  <SOAP-ENV:Header>[DETAILS NOT SHOWN]</SOAP-ENV:Header>
  <SOAP-ENV:Body id="_0">
    <GetTransactionDetailsResponse xmlns="urn:ebay:api:PayPalAPI">
    <Timestamp xmlns="urn:ebay:apis:eBLBaseComponents">2005-02-09T21:51:26Z</Timestamp>
    <Ack xmlns="urn:ebay:apis:eBLBaseComponents">Failure</Ack>
    <Errors xmlns="urn:ebay:apis:eBLBaseComponents" xsi:type="ebl:ErrorType">
      <ShortMessage xsi:type="xs:string">Authentication/Authorization Failed</ShortMessage>
      <LongMessage xsi:type="xs:string">Username/Password is incorrect</LongMessage>
      <ErrorCode xsi:type="xs:token">10002</ErrorCode>
      <SeverityCode xmlns="urn:ebay:apis:eBLBaseComponents">Error</SeverityCode>
    </Errors>
    <CorrelationID xmlns="urn:ebay:apis:eBLBaseComponents">Debugging-Info</CorrelationID>
    <Version xmlns="urn:ebay:apis:eBLBaseComponents">124.00</Version>
    <Build xmlns="urn:ebay:apis:eBLBaseComponents">1.0006</Build>
    <...other elements="" in="" response...="">
  </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

CorrelationID para relatar problemas ao PayPal

O valor retornado CorrelationIDé importante para o PayPal determinar a causa precisa de qualquer erro que você possa encontrar. Se você tiver que solucionar um problema com suas solicitações, sugerimos que você capture o valor CorrelationIDpara que você possa denunciá-lo ao PayPal.

Codificação de caracteres UTF-8

A API do PayPal supõe que todos os dados nas solicitações estejam em Unicode, especificamente, o formato de codificação de 8 bits (UTF-8) Unicode (ou UCS) Transformation Format.

Nas respostas, a API sempre retorna dados em UTF-8.

Formatos de data / hora

O esquema da API do PayPal para o SOAP define valores de data / hora como Hora Universal Coordenada (UTC / GMT), usando o formato ISO 8601 e do tipo ns:dateTime.

Um exemplo de data / hora é 2006-08-24T05: 38: 48Z

Tipo de dados do valor da moeda central

O tipo de dados da quantia monetária principal é chamado BasicAmountTypee é derivado de string. Todos os campos de valor monetário têm a seguinte estrutura:

  1. currencyIDatributo é obrigatório.
  2. O valor deve ter duas casas decimais, exceto no caso de moedas que não suportam valores decimais .
  3. O separador decimal deve ser um período (“.”).
  4. Você não deve usar nenhum separador de milhares.
  5. BasicAmountTypetem um tipo de dados ebl:CurrencyCodeType, que define um grande número de diferentes códigos de moeda. No entanto, para que seu processamento seja bem-sucedido, você deve definir currencyCode como um código de moeda válido .

Exemplo

O nome do campo Amount, é um exemplo; os nomes dos campos reais podem variar dependendo da operação específica da API .

<Amount currencyCode="USD">3.00</Amount>


FONTE: https://developer.paypal.com/docs/classic/api/PayPalSOAPAPIArchitecture/